このセクションは、reStructuredText(reST)の考え方や文法についての短いイントロダクションです。Sphinxユーザがドキュメントを作成するために十分な情報を提供します。reSTはシンプルに設計された、控えめなマークアップ言語ですので、理解するのにそれほど時間はかからないでしょう。
段落はreSTドキュメントにおける、もっとも基本的な要素です。段落は1行以上の空行で区切られた、シンプルなテキストの固まりです。 Pythonにおいてインデントが重要な意味を持つのと同様、reSTでもインデントは重要です。同じ段落のすべての行は、インデントを同じ高さにそろえて、左揃えにしなければなりません。
標準のreSTインラインマークアップは極めてシンプルです。
もしも、アスタリスクかバッククオートがテキスト中に使用する場合は、インラインマークアップの区切り文字と間違ってしまうことがあります。そのような場合には、バックスラッシュ(訳注:日本語フォントだと円記号)を使ってエスケープしてください。
このマークアップにはいくつかの制限があります。
これらの制限は、docutilsの将来のバージョンでも残るでしょう。
reSTには、”解釈済みテキストロール”というものが許されています。これは、 :ロール名:`解釈済みテキスト` という文法になります。これは、囲まれているテキストは特別な方法で解釈させることができる、というものです。Sphinxはこれをつかって、意味のマークアップと、識別子のマークアップを行っています。これに関しては別のセクションで説明します。
リストを表現するマークアップはほぼ結果の見た目通りです。パラグラフの最初をアスタリスクで開始して、適切にインデントをしてやるだけです。ナンバー付きのリストも同様です。 # を使うことで、ナンバリングを自動で行うこともできます:
* これは丸が行頭に付くリストです
* このリストには2つの項目があります。2つめの
項目は2行にまたがっています。
1. これはナンバー付きリストです。
2. これも2つの項目があります。
#. これはナンバー付きリストです。
#. これも2つの項目があります。
テストされたリストも使用することができますが、親のリストとは空白行で区切る必要があります:
* これは
* リストです
* ネストされたリストです
* サブ項目です
* こうやって、親のリストを継続することもできます
定義リストは以下のようにして作成します:
用語 (行末までが用語です)
用語の定義です。定義はインデントする必要があります。
空白行で区切ることで、定義に複数のパラグラフを書くことができます。
次の用語
説明
パラグラフは周囲のパラグラフよりも深いインデントにしてやる必要があります。
リテラルコードブロックは、前の段落の行末を特別な記号 :: にすることで開始することができます。リテラルコードブロックはインデントする必要があります。また、他のパラグラフ同様、空白行で前後をかこう必要があります:
これは通常のテキストのパラグラフです。次のパラグラフはコードサンプルです::
この中はreSTで処理されません。そのまま出力されます。
ただし、コードブロックのインデントだけは削除されます。
複数行記述することもできます。
ここからは通常のテキストのパラグラフに戻ります。
:: マーカーの扱いはとてもスマートです:
3つ目のルールが適用されるため、上記のサンプルの最初の段落中の２つめの文をレンダリングすると、 “次のパラグラフはコードサンプルです:” という表記になります。
`リンクテキスト <http://ターゲットURL>`_ という書くことで、外部のウェブサイトへのリンクを埋め込むことができます。もしリンクテキストがウェブのアドレスである場合には、特別なマークアップは必要ありません。パーサーが通常のテキスト中でリンクか、メールアドレスを見つけると、そのままそれにリンクを埋め込んでくれます。
内部リンクは特別なreSTのロールを通じて行われます。詳しくは、特別なマークアップ 自由な場所へのクロスリファレンス のセクションを見てください。
セクションのヘッダは、セクションのタイトルを句読点などの記号の文字でアンダーラインを引くことで設定します。必要に応じてでオーバーラインも併用することができます。アンダーラインはテキストと同じか、それ以上の長さにする必要があります:
================
これは見出しです
================
通常は、文字の種類と見出しのレベルは関係ないため、どの文字でも使用することができます。使用していない種類のアンダーラインが出てくると、見出しのレベルが一段変わる、というルールになっています。参考までに、Pythonドキュメントで使っている慣例について紹介しておきます
もちろん、どのようなマークアップ文字を選択しても自由ですし、組み合わせることで、より深い、ネストレベルを使用することもできます。reSTの文章を参照してください。ただし、ほとんどの対象となる出力フォーマット(HTML, LaTeX)は、ネストできる深さには限界が設定されている、ということは忘れないでください。
“明示的なマークアップ”というのは、reSTの中では特別な操作の必要な多くの構成要素のために使用されます。例えば脚注や、言語別のハイライトをする特別な段落、コメントや処理系(Sphinx)に対する指示などです。
明示的なマークアップのブロックは .. で始まる行から始まります。先頭の記号の後ろにはホワイトスペースが一つ入ります。そして、インデントが同じレベルになる次の段落までが１つのブロックとして扱われます。通常のパラグラフと、明示的なマークアップのブロックの間には一行以上のスペースを空ける必要があります。このような説明を聞くとわかりにくいと感じる人も多いと思いますが、実際に自分で書いてみると十分に直感的であるということがわかるでしょう。
ディレクティブは汎用の明示的マークアップです。reSTの拡張のためのメカニズムの一つで、ロールが指定されることがあります。Sphinxはこのディレクティブをかなり多用しています。
基本的に、ディレクティブは名前、引数、オプション、コンテンツなどで構成されています。これらの用語を覚えておいてください。これらは次の章でカスタムディレクティブの紹介を行う際に利用します。以下にサンプルを示します:
.. function:: foo(x)
foo(y, z)
:bar: no
ユーザから入力されたテキストのうち、１行を返します。
function がディレクティブの名前です。ここでは二つの引数が与えられています。1行目の残りの部分と、2行目が引数です。そして1つのオプション bar も同様に設定されています。見ての通り、オプションは引数のある行のすぐ次の行に書かれていています。そして、目印としてコロンが付いています。
ディレクティブのコンテンツというのは、空白行の後に続くブロックで、ディレクティブが開始された地点よりも深いインデントでくくられています。
reSTは画像に関するディレクティブもサポートしています。以下のように使用します。:
.. image:: gnu.png
(オプション)
Sphinx内で使用する場合には、ソースファイルからの相対パスか、トップのソースディレクトリからの絶対パスでファイル名(ここでは gnu.png)を指定します。例えば、 sketch/spam.rst というソースファイルからは、 images/spam.png, ../images/spam.png, /images/spam.png というように書くことができます。
このディレクティブを使用すると、Sphinxはビルド時に、指定された画像ファイルを出力ディレクトリのサブディレクトリにコピーします。HTML出力の場合には、 _static といったディレクトリにコピーされます。
イメージサイズに関するオプション(width と height)は以下のように解釈されます。もし単位が無い、もしくは単位がpixelsの場合には、与えられたサイズは出力するチャンネルがピクセルをサポートしているかどうかだけが考慮されます。例えば、LaTeX出力はこれをサポートしていません。田の単位(ポイントを表す pt など)はHTMLでもLaTeXでも使用されます。
Sphinxは標準のdocutilsを拡張していて、拡張子としてアスタリスク(*)を受け取れるようになっています:
.. image:: gnu.*
アスタリスクが指定されると、Sphinxは指定されたパターンにマッチするすべての画像フォーマットを検索して、使用するタイプを決定します。それぞれのビルダーは、候補となるベストのイメージを選択します。 gnu.* にマッチするファイル名として、 gnu.pdf と、 gnu.png がソースツリーの中に存在していたとします。LaTeXビルダーは前者のPDFを、HTMLビルダーは後者のPNGを優先的に利用します。
バージョン 0.4 で変更: ファイル名の末尾をアスタリスク(*)にできる機能が追加されました。
バージョン 0.6 で変更: イメージパスとして、ソースフォルダのルートからの絶対パスが指定できるようになりました。
脚注を作成するためには、脚注を書きたい場所で [#name]_ というマークアップを書きます。そして、脚注の本体をドキュメントの下の方の “脚注” のためのrubric見出しの中に書きます:
Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
.. rubric:: 脚注
.. [#f1] 最初の脚注のテキストです。
.. [#f2] ２番目の脚注のテキストです。
脚注の数値を明示的に指定([1]_)することもできますし、名前を指定しないで脚注の自動採番([#])をさせることも可能です。
標準のreSTでも引用はサポートしていますが、Sphinx独自の追加の機能としては、引用が”グローバル”ということです。そのため、全ての引用はすべてのファイルから参照することができます。以下のように使用します:
Lorem ipsum [Ref]_ dolor sit amet.
.. [Ref] 参考になった書籍、論文、URL、その他
引用は、脚注と同じように使用できますが、ラベルは数字ではありませんし、 # でも始まりません。
reSTは”置換”をサポートしています。これは、テキスト中の |名前| で指定された箇所に、テキストや、マークアップを挿入します。脚注と同じように明示的なマークアップブロックを使って定義します:
.. |name| replace:: リプレースされる *テキスト*
詳しくは reSTリファレンスの置換の説明 を参照してください。
いくつかの置換をすべてのドキュメントで使用したい場合には、置換の宣言を別のファイルに切り出して、その置換を行いたいすべてのドキュメントの冒頭で include ディレクティブを使用してインクルードする方法があります。この場合は、他のソースファイルとは別の拡張子を付けるようにしましょう。同じ拡張子にすると、Sphinxはリンクされていないドキュメントとして警告を出力してしまいます。
Sphinxはデフォルトの置換をいくつか定義しています。詳しくは default-substitutions を参照してください。
上記の脚注のような適切な構造をしていない明示的マークアップのブロックはすべてコメントとみなされます:
.. これはコメントです。
コメントがスタートした行からインデントすることによって、複数行コメントにすることができます:
..
このインデントされたブロック
全体がコメントです
この行もまだコメントです
エムダッシュ(アルファベットのMと同じ幅を持つダッシュ)や、コピーライトの記号などの特殊記号をreSTに入れる場合にはユニコードの文字として直接入れるのが一番簡単な方法です。Sphinxはデフォルトでは、UTF-8であるとみないしてソースコードを読み込みます。 source_encoding の設定値を変更することで、このデフォルトのエンコーディングを変更することができます。
reSTのドキュメントを書いていると、良く遭遇する問題がいくつかあります: