コンテンツにスキップ
NextPDF

NextPDF ドキュメントの構成

概要

「概要」という見出しのセクション

NextPDF マニュアルは、定められた取り決めに従って拡張されます。各ページは、1 つのトピック、1 つの Diataxis モード、1 つのページ種別を持ちます。各ページ種別には、必須となるレベル 2 見出しのセットがあります。いくつかのマニフェストとゲートによって、マニュアルが拡張されても構造は正しく保たれます。

このページでは、貢献内容が適切な場所に収まるように、そのシステムの全体像を示します。正確な見出し一覧、引用規則、ゲート組み込み手順を含む完全かつ規範的な取り決めは、内部ガバナンス文書である docs/style/expansion-standard.md にあります。まずこのページを読み、執筆時にその文書を参照してください。

ページ種別の選択

「ページ種別の選択」という見出しのセクション

ページを追加するか、既存のページを拡張するかを判断するには、次のルールを順番に適用してください。

  1. その内容が、読者が既存のページにあるとは期待しない独立したトピックである場合は、新しいページを追加します。
  2. その内容が、既存のページがすでに扱っているトピックを補完する内容である場合は、そのページを拡張します。
  3. その内容が、インストール、クイックスタート、タスクのページを肥大化させる詳細情報である場合は、別のページに移動してリンクします。
  4. それ以外の場合は、既存のページを拡張します。

ページを用意することが決まったら、その Diataxis モードを設定します。これによってページ種別が確定します。

  • Tutorial は学習者に教えるためのものなので、レシピ形式のタスクガイドを使用します。
  • How-to は習熟した読者がタスクを完了できるよう支援するためのものなので、タスクガイド、サーバー API ガイド、または SDK ガイドを使用します。
  • Reference は正確な事実を記述するためのものなので、API リファレンスまたはインデックスページを使用します。
  • Explanation は理解を深めるためのものなので、開発者ガイドまたはプレミアム機能ガイドを使用します。

平易な表現はすべてのモードにおける基本であり、それ自体が 1 つのモードではありません。

ページ種別のカタログ

「ページ種別のカタログ」という見出しのセクション

マニュアルの取り決めでは、次の種別が認められています。ページに API テーブルがある場合は、必ず既存の種別を再利用します。ラベルのみの新しい種別を導入できるのは、API テーブルのないページに限ります。

  • インデックス種別：section-index、api-index、extension-index。
  • リファレンス種別：api-reference。これは、サーバーや Python SDK のリファレンスを含め、標準的な API テーブルを持つすべてのページで再利用します。
  • 説明種別：developer-guide。これは、サーバーや Python SDK のガイドを含め、アーキテクチャ、ライフサイクル、拡張ポイントに関する説明ページで再利用します。
  • ラベルのみの新しい種別：premium-feature-guide と task-guide で、いずれも API テーブルのないページ用です。

すべてのページは ## At a glance で始まります。すべての api-reference ページは、共有 API テーブルと Development notes 見出しを備えています。必須の見出しは厳密にレベル 2 で、それぞれ独立した行に置きます。その下に見出しを追加してもかまいません。

執筆チェックリスト

「執筆チェックリスト」という見出しのセクション

ページを書くときは、これら 2 つのチェックリストの両方を満たしてください。内部標準では、各項目を規範として記述し、その根拠となる標準へのリンクを示しています。

開発者にとっての使いやすさ：

  • 実行可能なサンプルは examples/ または tests/Cookbook から取得し、各コードブロックに title= 情報文字列を付けてください。
  • 前提条件はフロントマターと冒頭部分に記載してください。
  • 出力を返すサンプルについては、期待される出力を示してください。
  • コードブロックはコピー＆ペーストですぐ使える状態に保ちます。1 ブロックにつき 1 言語にし、初回使用時は完全な名前を記載し、末尾にはプロンプト文字を残しません。
  • 既定で安全なコードを示します。本番向けのサンプルでは、最も具体的な NextPDF 例外を用いた try/catch を使用し、空の catch ブロックは決して書きません。
  • 関連リンクで締めくくり、フロントマターの related: を設定します。

翻訳への対応：

  • 機械翻訳が冗長にならないよう、1 文に 1 つの考えを書いてください。
  • ほとんどの対象言語では文字数が増えるため、見出しとラベルは短く保ってください。
  • 慣用表現は避けてください。
  • シンボル名、設定キー、CLI フラグ、例外名はコード書式のままにします。PDF/A-4、PAdES、eIDAS などの標準名は決して翻訳しません。
  • フロントマターの i18n_ready と xliff_segments を正確に設定し、Unicode NFC で記述してください。

文体、コードサンプル、用語、引用スタイルについては、内部標準から参照されている承認済みのスタイルオーバーライドシートに従ってください。

ゲートの組み込み

「ゲートの組み込み」という見出しのセクション

新しいページは、次の順序で組み込みます。

  1. フロントマターがサイトスキーマに一致するようにページのひな形を作成します。
  2. 本文は、ページ種別ごとに必須となる見出しに沿って執筆します。
  3. 次の { path, owner, kind, headings[] } エントリを docs/manual-contract.json に追加します。パスは src/content/docs からの相対パスで、スラッシュ区切りを使用し、先頭のスラッシュと .. は含めません。
  4. API リファレンスの場合は、ページのシンボルを docs/api-coverage-manifest.json に追加します。各シンボルはページに記載され、かつソースに存在している必要があります。
  5. ページが新しいソースリポジトリに由来する場合に限り、docs/source-manifest.json を更新します。
  6. ページを astro.config.mjs の適切なサイドバーグループに、明示的なエントリとして追加します。
  7. 英語のみのページの場合は、17 個すべてのロケールセルを missing に設定したロケールカバレッジ行を追加します。
  8. ドキュメントゲート、ビルド、パフォーマンスバジェットを実行します。

サイト所有のページは src/content/docs 配下に置き、owner を nextpdf-docs に設定し、aggregate（集約）マーカーは決して付けません。集約されたページはソースリポジトリ由来であり、その公開フラグはソースのフロントマターにあるため、ここではなくソース側で編集します。

関連項目

「関連項目」という見出しのセクション
  • Integrations：多数のパッケージにまたがるマニュアル構成を実践している、最大規模の実例です。
  • 内部ガバナンス文書である docs/style/expansion-standard.md には、完全な取り決めが記載されています。各ページ種別の正確な見出し一覧、引用規則、ゲート組み込みの完全な手順が含まれます。