reStructuredText形式のドキュメントを書くことに馴染めない人には、(GitHub風の)Markdownで書かれるドキュメントもサポートします。
理想的には、この全体のドキュメントをreStructuredText形式にする方を好みますが、これにより学習曲線をもたらされる人々がいることも理解しています。
新しいMarkdownドキュメントを生成するには、関連したディレクトリに.md
拡張子を持つファイルを単に作成します。Sphinxは自動的にこれがMarkdownドキュメントと理解し、適切に描画します。
Markdownは組み立てユニットではないため、Sphinx reStructuredTextディレクティブと役割の多くをサポートしません。内部的なリンクは相対的なパスを使って行われなければならず、:github:
のような役割はMarkdownとは等価ではありません。
新しいドキュメントの追加について、Markdownドキュメントをtocree
へ追加するために関連するindex.rst
ファイルを編集する必要があります。Markdown はtoctree自身をサポートしません。
コード構文ハイライトはPygmentsを使ってサポートおよびパースされます。つまり、互換性のある言語名は適切な場所で使われるべきです。