Sphinx クイックスタートテンプレート

この記事は、「ドキュメントを書いて LLVM のドキュメントに追加したい」という状態の人が、できるだけ早く、無駄なくドキュメントを書き始めることができるようにすることを目的としています。

概要

LLVM ドキュメントは、マークダウンに似たマークアップ構文であるreStructuredTextで記述されています（ただし、はるかに強力です）。LLVM ドキュメントサイト自体は、もともと Python ドキュメント用に書かれたドキュメントジェネレーターであるSphinxを使用しています。

このテンプレートの使い方

この記事はdocs/SphinxQuickstartTemplate.rstにあります。これをテンプレートとして使用するには、コピーを作成し、テキストエディターで開いてください。次に、ドキュメントを記述し、新しい記事を llvm-commits に送信してレビューしてもらいます。

この記事の reStructuredText ソースファイルを表示するには、右側のサイドバーにあるソースを表示をクリックしてください。

執筆ガイドライン

内容に焦点を当ててください。必要に応じて、後で Sphinx（reStructuredText）構文を修正するのは簡単です。ただし、reStructuredText は一般的なプレーンテキストの規則を模倣しようとしているため、非常に自然なはずです。ドキュメントを作成する際に reStructuredText 構文の基本的な知識があると便利です。そのため、このドキュメントの後半（セクションの例から始まる）には、ユースケースの 99% をカバーする例が示されています。

もう一度言います。内容に焦点を当ててください。ただし、Sphinx の出力を実際に確認する必要がある場合は、docs/README.txtで情報を参照してください。内容が完成したら、.rstファイルを llvm-commits に送信してレビューしてもらいます。

新しい記事の作成

新しい記事を作成する前に、次の質問を検討してください。

  1. なぜ私はこのドキュメントを読みたいと思うのか？

  2. このドキュメントを理解するために、私は何を知っておくべきか？

  3. このドキュメントを読み終えたとき、私は何を学んでいるのか？

標準的なベストプラクティスは、記事をタスク指向にすることです。通常、ドキュメント化しているトピックに関する既存の「ハウツー」記事がすでに存在しない限り、「ハウツー」を行うことに基づかないドキュメントを作成すべきではありません。この理由は、最初に読む「ハウツー」記事がないと、トピックに不慣れな人がより高度な概念的な記事を理解するのが難しい場合があるためです。

タスク指向の記事を作成する場合は、既存の LLVM 記事に従って、HowTo*.rstで始まるファイル名を付けてください。この形式は通常、他の人が理解するのが最も簡単で、最も役立ちます。

内容に焦点を当ててください（ええ、もう一度言わざるを得ませんでした）。

このドキュメントの残りの部分では、このファイルを新しいドキュメント用のファイルにコピーした後、テキストエディターで読むことを目的とした reStructuredText マークアップ構造の例を示します。

セクションの例

記事には、1 つ以上のセクション（つまり、見出し）を含めることができます。セクション（上記のセクションの例など）は、ドキュメントの構造を与えるのに役立ちます。このドキュメントで使用されているのと同じ種類のアドーンメント（例：======対------）を使用してください。アドーンメントは、その上のテキストと同じ長さである必要があります。Vim ユーザーの場合、yypVr=のバリエーションが便利かもしれません。

ネストされたサブセクションの例

サブセクションは、他のサブセクションの下にネストすることもできます。セクションの詳細については、Sphinx のreStructuredText Primerを参照してください。

テキストの書式設定

テキストは強調、太字、または等幅にできます。

新しい段落を作成するには、単に空白行を挿入します。

リスト

reStructuredText を使用すると、順序付きリストを作成できます…

  1. #.で始まるリストは、自動的に番号が付けられます。

  2. これは 2 番目のリスト要素です。

    1. インデントを使用して、ネストされたリストを作成します。

…だけでなく、順序なしリストも作成できます。

  • 項目。

    • より深い項目。

  • その他の項目。

コードブロック

このようなコードブロックを作成できます

int main() {
  return 0;
}

シェルセッションの場合は、consoleコードブロックを使用します（一部の既存のドキュメントではbashを使用します）

$ echo "Goodbye cruel world!"
$ rm -rf /

LLVM IR を表示する必要がある場合は、llvmコードブロックを使用します。

define i32 @test1() {
entry:
  ret i32 0
}

必要な可能性のあるその他の一般的なコードブロックには、c、objc、make、およびcmakeがあります。それ以上のものが必要な場合は、サポートされているコードブロックの完全なリストを参照してください。

ただし、意味のあるコンテンツを追加できる場合は、構文の強調表示に時間を費やさないでください。迷った場合は、次のように構文の強調表示なしで整形済みテキストを表示します

                      .
                       +:.
                   ..:: ::
                .++:+:: ::+:.:.
               .:+           :
        ::.::..::            .+.
      ..:+    ::              :
......+:.                    ..
      :++.    ..              :
        .+:::+::              :
        ..   . .+            ::
                 +.:      .::+.
                  ...+. .: .
                     .++:..
                      ...

ドキュメントの生成

HTML ドキュメントをソースからローカルで生成して、どのように表示されるかを確認できます。通常のビルドツールに加えて、Sphinxと必要な拡張機能を、llvm-projectチェックアウト内の次のコマンドを使用してインストールする必要があります

pip install --user -r ./llvm/docs/requirements.txt

次に、cmake を実行して、llvm-projectチェックアウト内でドキュメントをビルドします

mkdir build
cd build
cmake -DLLVM_ENABLE_SPHINX=On ../llvm
cmake --build . --target docs-llvm-html

すでに Cmake ビルドが設定されていて、それを再利用したい場合は、CMake 変数LLVM_ENABLE_SPHINX=Onを設定するだけです。

その後、生成されたドキュメントはbuild/docs/htmlフォルダーにあります。