Write Vignette

ビネットの記述

Rパッケージの長文ドキュメントビネットを作成する。

使用タイミング

• パッケージの「はじめに」チュートリアルを追加する時
• 複数の関数にまたがる複雑なワークフローを文書化する時
• ドメイン固有のガイドを作成する時（例：統計手法）
• CRAN投稿で関数ヘルプを超えたユーザー向けドキュメントが必要な時

入力

• 必須: ドキュメント化する関数を持つRパッケージ
• 必須: ビネットのタイトルとトピック
• 任意: 形式（R MarkdownまたはQuarto、デフォルト：R Markdown）
• 任意: ビネットが外部データやAPIを必要とするかどうか

手順

ステップ1: ビネットファイルの作成

usethis::use_vignette("getting-started", title = "Getting Started with packagename")

期待結果： YAMLフロントマターを持つvignettes/getting-started.Rmdが作成される。DESCRIPTIONのSuggestsフィールドにknitrとrmarkdownが追加される。vignettes/ディレクトリが存在する。

失敗時： usethis::use_vignette()が失敗する場合、作業ディレクトリがパッケージルート（DESCRIPTIONが含まれる）であることを確認する。knitrがインストールされていない場合はinstall.packages("knitr")を実行する。手動で作成する場合はvignettes/ディレクトリとファイルを作成し、YAMLフロントマターに3つの%\Vignette*エントリすべてが含まれていることを確認する。

ステップ2: ビネットコンテンツの記述

---
title: "Getting Started with packagename"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with packagename}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Introduction

Brief overview of what the package does and who it's for.

## Installation

```r
install.packages("packagename")
library(packagename)
```

## Basic Usage

Walk through the primary workflow:

```r
# Load example data
data <- example_data()

# Process
result <- main_function(data, option = "default")

# Inspect
summary(result)
```

## Advanced Features

Cover optional or advanced functionality.

## Conclusion

Summarize and point to other vignettes or resources.

期待結果： ビネットのRmdファイルに「はじめに」、インストール、基本的な使い方、高度な機能、まとめのセクションが含まれる。コード例がパッケージのエクスポートされた関数を使用して表示可能な出力を生成する。

失敗時： 例が実行に失敗する場合、devtools::install()でパッケージがインストールされているか確認する。例が（devtools::load_all()ではなく）library()呼び出しでパッケージ名を使用していることを確認する。外部リソースを必要とする関数には、実行せずにコードを表示するためにeval=FALSEを使用する。

ステップ3: コードチャンクの設定

異なる目的でチャンクオプションを使用する：

# 標準的な評価チャンク
{r example-basic}
result <- compute_something(1:10)
result

# コードを表示するが実行しない（例示目的）
{r api-example, eval=FALSE}
connect_to_api(key = "your_key_here")

# コードを非表示にして実行する（出力のみ表示）
{r hidden-setup, echo=FALSE}
library(packagename)

# グローバルオプションを設定
{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5
)

期待結果： include=FALSEを持つsetupチャンクがグローバルオプション（collapse、comment、fig.width、fig.height）を設定する。チャンクが適切に設定される：例示コードにはeval=FALSE、隠しセットアップにはecho=FALSE、インタラクティブな例には標準チャンク。

失敗時： チャンクオプションが効果を発揮しない場合、構文が{r chunk-name, option=value}形式（カンマ区切り、論理値に引用符なし）を使用していることを確認する。setupチャンクがドキュメントの先頭に配置されていることを確認する。

ステップ4: 外部依存関係の処理

ネットワークアクセスやオプションパッケージが必要なビネットの場合：

{r check-available, include=FALSE}
has_suggested <- requireNamespace("optionalpkg", quietly = TRUE)

{r use-suggested, eval=has_suggested}
optionalpkg::special_function()

長時間実行される計算の場合、結果を事前計算して保存する：

# Save pre-computed results to vignettes/
saveRDS(expensive_result, "vignettes/precomputed.rds")

# Load in vignette
{r load-precomputed}
result <- readRDS("precomputed.rds")

期待結果： 外部依存関係が適切に処理される：オプションパッケージはrequireNamespace()で条件付き読み込み、ネットワーク依存コードはeval=FALSEまたはtryCatch()を使用、コストのかかる計算は事前計算済みの.rdsファイルを使用する。

失敗時： オプションパッケージが利用不可のためにCRANでビネットが失敗する場合、それらのセクションを条件変数で囲む（例：eval=has_suggested）。事前計算済みの結果は、.rdsファイルがvignettes/ディレクトリに含まれていて相対パスで参照されていることを確認する。

ステップ5: ビネットのビルドとテスト

# Build single vignette
devtools::build_vignettes()

# Build and check (catches vignette issues)
devtools::check()

期待結果： ビネットがエラーなくビルドされる。HTML出力が読みやすい。

失敗時：

• pandocの欠如：.RenvironでRSTUDIO_PANDOCを設定する
• パッケージが未インストール：先にdevtools::install()を実行する
• Suggestsの欠如：DESCRIPTIONのSuggestsに記載されたパッケージをインストールする

ステップ6: パッケージチェックでの確認

devtools::check()

ビネット関連のチェック：正しくビルドされる、時間がかかりすぎない、エラーがない。

期待結果： devtools::check()がビネット関連のエラーや警告なしでパスする。ビネットがCRANの時間制限内（通常60秒以内）にビルドされる。

失敗時： ビネットがチェック失敗を引き起こす場合、一般的な修正には：DESCRIPTIONへのSuggestsパッケージの追加、低速なチャンクへのeval=FALSEの使用によるビルド時間の短縮、VignetteIndexEntryがタイトルと一致していることの確認が含まれる。ビネット固有のエラーを分離するためにdevtools::build_vignettes()を別途実行する。

バリデーション

• devtools::build_vignettes()でビネットがエラーなくビルドされる
• すべてのコードチャンクが正しく実行される
• VignetteIndexEntryがタイトルと一致する
• devtools::check()がビネット警告なしでパスする
• ビネットがpkgdownサイトの記事に表示される（該当する場合）
• ビルド時間が妥当である（CRANでは60秒未満）

よくある落とし穴

• VignetteIndexEntryの不一致: YAMLのインデックスエントリはvignette(package = "pkg")でユーザーに表示されるものと一致しなければならない
• vignette YAMLブロックの欠如: 3つの%\Vignette*行すべてが必要
• CRANには遅すぎるビネット: 結果を事前計算するか、コストのかかる処理にeval=FALSEを使用する
• pandocが見つからない: RSTUDIO_PANDOC環境変数が設定されていることを確認する
• パッケージの自己参照: ビネット内ではdevtools::load_all()ではなくlibrary(packagename)を使用する

関連スキル

• write-roxygen-docs - ビネットチュートリアルを補完する関数レベルのドキュメント
• build-pkgdown-site - ビネットはpkgdownサイトの記事として表示される
• submit-to-cran - CRANにはビネットに固有の要件がある
• create-quarto-report - R Markdownビネットの代替としてのQuarto