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

はじめに と クイックスタート

このドキュメントは、Markdown の経験がない場合でも、できるだけ早くドキュメントを書き始めることを目的としています。目標は、「LLVM のドキュメントを作成し、それを LLVM のドキュメントに追加したい」という状態の人を、できるだけ無駄なく、llvm-commits にメールで送信できる有用なドキュメントにすることです。

このドキュメントは、docs/MarkdownQuickstartTemplate.md にあります。コピーして、テキストエディタで新しいファイルを開き、ドキュメントを書き、新しいドキュメントを llvm-commits にレビューのために送信してください。

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

もう一度言います。コンテンツに焦点を当ててください。ただし、Sphinx の出力を確認する必要がある場合は、docs/README.txt を参照してください。

コンテンツが完成したら、.md ファイルを llvm-commits にレビューのために送信してください。

ガイドライン

最初のセクションで、以下の質問に答えてみてください

  1. なぜこのドキュメントを読む必要があるのか？

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

  3. このドキュメントの終わりまでに、何を学べるのか？

最初のセクションの一般的な名前は、はじめに、概要、または 背景 です。

可能であれば、ドキュメントを「ハウツー」にしてください。他の「ハウツー」ドキュメントのように、HowTo*.md のような名前を付けてください。この形式は通常、他の人が理解するのに最も簡単で、最も役立つものです。

通常、トピックに関する「ハウツー」がすでにある場合を除き、「ハウツー」以外のドキュメントを作成するべきではありません。これは、最初に読むべき「ハウツー」ドキュメントがないと、より高度なドキュメントを理解するのが難しいからです。

コンテンツに焦点を当ててください（そうです、もう一度言わざるを得ませんでした）。

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

サンプルセクション

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

段落を区切るには、空白行を使用します。

見出し（上記の サンプルセクション など）は、ドキュメントの構造を示します。

サンプルサブセクション

このようにリンクを作成します。また、長いリンクの場合、フローが中断されないため、より読みやすいより洗練された構文もあります。 [リンク名]: <URL> ブロックは、ドキュメントの後半のほぼどこにでも配置できます。

リストは、このように作成できます

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

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

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

順序なしリストも使用できます。

  • 内容。

    • より深い内容。

  • その他の内容。

サンプルサブサブセクション

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

int main() {
  return 0;
}

Markdown の拡張として、使用するハイライターを指定することもできます。

int main() {
  return 0;
}

シェルセッションの場合は、console コードブロックを使用します。

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

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

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

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

ただし、意味のあるコンテンツを追加できるときに、構文ハイライトをいじって時間を無駄にしないでください。迷った場合は、次のように構文ハイライトなしで整形済みのテキストを表示してください

                      .
                       +:.
                   ..:: ::
                .++:+:: ::+:.:.
               .:+           :
        ::.::..::            .+.
      ..:+    ::              :
......+:.                    ..
      :++.    ..              :
        .+:::+::              :
        ..   . .+            ::
                 +.:      .::+.
                  ...+. .: .
                     .++:..
                      ...
これがそれほど深くなる必要がないことを願っています

このドキュメントで示されているよりも凝ったことをする必要がある場合は、リストにメールを送信するか、Common Mark 仕様を確認してください。 Sphinx 固有の統合ドキュメントは、myst-parser ドキュメントにあります。

ドキュメントの生成

[Sphinx クイックスタートテンプレート](project:SphinxQuickstartTemplate.rst#ドキュメントの生成) を参照してください