Macでドキュメント生成ツール-Sphinx-を使う (2)
Sphinxで構造化されたドキュメントを作ってHTMLで出力しよう
前回
でMacにSphinxを導入できたので今回は本格的にドキュメントを作ってみます．
index.rstを編集する
まずは中身を見てみましょう．Sphinx文書はreStructuredText形式で書かれます．
.. a documentation master file, created by sphinx-quickstart on Sat Sep 26 08:07:51 2015. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to a's documentation! ============================= Contents: .. toctree:: :maxdepth: 2 Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`
１つづつ確認していきます．
初めの
.. a documentation master file, created by sphinx-quickstart on Sat Sep 26 08:07:51 2015. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive.
はコメントアウトです．Sphinxプロジェクト作成ユーティリティが自動生成したコメントが埋め込まれています．文法としては，スペースを何も入れずに「.」を２つ．次に半角スペースを入れてからコメントを書き始めます．改行したらインデントをするとコメントの中の扱いになります．reStructuredTextはインデントが文法に組み込まれているので正確にインデントしないと，make htmlしたときにエラーを吐いてしまいます．コメントが終わったらインデントをやめて空白行を入れてあげましょう．これでコメントアウトの終了を明示的に示したことになります．
Welcome to a's documentation! =============================
は見ての通り章，節のタイトルです．セクションにしたい行の下，もしくは上下に「= - ` : ' " ~ ^ _ * + # < >」等の記号でラインを引きます．文字数はセクションのバイト数より多くする必要があり，上下に引くときは同じ文字数にします．順番は決まっておらず，そのファイル内で使用した順番で見出しのレベルが１つづつ下がる決まりになっています．また，同じ記号でも上下に引く場合と下だけに引く場合で違う記号の扱いを受けます．例を書いておきましょう．
============= レベル１ ============= レベル２ ------------- レベル３ ^^^^^^^^^^^^^ レベル４ =============
これはHTMLでは
<h1>レベル１</h1> <h2>レベル２</h2> <h3>レベル３</h3> <h4>レベル４</h4>
に対応します．rstの記号を入れ替えてもまったく同じの意味になります．
次の説明に移ります．
Contents: .. toctree:: :maxdepth: 2
Content: はただの文字です．余計なインデントをしてはいけないことに注意しましょう．その下の .. toctree:: に関しては説明が必要でしょう．この書き方はディレクティブというものでLaTeXにおけるenvironmentと同じようなものです．例えば上記のコードはLaTeX風に書くと
\begin{toctree}[maxdepth=2] \end{toctree}
となります．オプションは他にも色々ありますがここでは省略します．rstにはディレクティブが終わる場所が明示されていないようにも見えますが，ここもインデントを終了することで\end{toctree}を示します．
ディレクティブの文法について説明しておきます．topicというディレクティブを使うとしましょう．まず，文頭に「..」と書き，半角スペースを一つ．更に「:」を２つ書き改行し，ディレクティブの中に入れるものはインデントして書きます．
それではtoctreeディレクティブを使ってみましょう．toctreeは他のrstファイルを自分のファイルの子要素に指定するものです．今，index.rstがある階層にいるものとします．
子要素にするドキュメントを入れるファイルを作り，その中に子文書child1.rstとchild2.rstを作ります．
cd source mkdir children cd children echo -e "これは子文書１です\n=========================================" > child1.rst echo -e "これは子文書２です\n=========================================" > child2.rst cd ../..
そうしたら，toctreeのところを
.. toctree:: :maxdepth: 2 children/child1 children/child2
と書き換えて Makefile のあるディレクトリに戻り make html します．maxdepthとその下のchildren/child1の間にはインデントを入れた空白行を入れないとエラーになります．他にエラーが起きるときはインデントのスペースやタブ文字の個数が全て統一されているか確認して下さい．index.rstは自動生成されたコードが混じるので思わない所でスペースの数が違ったりします．
ビルドしてHTMLを作成する
以上で階層化された文書が組み込まれます．子要素からも更に子要素が指定できるので明確に階層化された文書を簡単に作ることができます．ここまでの結果で出力されたindex.htmlを見てみましょう．
詳しいことはTOCツリー — Sphinx 1.3.2 ドキュメントを参照して下さい．これまでの知識があれば読めるような記事を書けていれば幸いです．
最後の
* :ref:`genindex` * :ref:`modindex` * :ref:`search`
は入門には早いという理由で今回は触れないことにします．文書には索引があるわけで，その索引へのリンクを入れることになりますが，索引ファイルは別で作らなければならないのでこれだけでは使えません．邪魔であれば消しても良いと思います．
