読者です 読者をやめる 読者になる 読者になる

Macでドキュメント生成ツール-Sphinx-を使う (2)

Sphinxで構造化されたドキュメントを作ってHTMLで出力しよう

前回

rwilyp.hatenablog.com

MacSphinxを導入できたので今回は本格的にドキュメントを作ってみます.

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`

1つづつ確認していきます.

初めの

.. 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プロジェクト作成ユーティリティが自動生成したコメントが埋め込まれています.文法としては,スペースを何も入れずに「.」を2つ.次に半角スペースを入れてからコメントを書き始めます.改行したらインデントをするとコメントの中の扱いになります.reStructuredTextはインデントが文法に組み込まれているので正確にインデントしないと,make htmlしたときにエラーを吐いてしまいます.コメントが終わったらインデントをやめて空白行を入れてあげましょう.これでコメントアウトの終了を明示的に示したことになります.

Welcome to a's documentation!
=============================

は見ての通り章,節のタイトルです.セクションにしたい行の下,もしくは上下に「= - ` : ' " ~ ^ _ * + # < >」等の記号でラインを引きます.文字数はセクションのバイト数より多くする必要があり,上下に引くときは同じ文字数にします.順番は決まっておらず,そのファイル内で使用した順番で見出しのレベルが1つづつ下がる決まりになっています.また,同じ記号でも上下に引く場合と下だけに引く場合で違う記号の扱いを受けます.例を書いておきましょう.

=============
レベル1
=============

レベル2
-------------

レベル3
^^^^^^^^^^^^^

レベル4
=============

これはHTMLでは

<h1>レベル1</h1>

<h2>レベル2</h2>

<h3>レベル3</h3>

<h4>レベル4</h4>

に対応します.rstの記号を入れ替えてもまったく同じの意味になります.

次の説明に移ります.

Contents:

.. toctree::
   :maxdepth: 2

Content: はただの文字です.余計なインデントをしてはいけないことに注意しましょう.その下の .. toctree:: に関しては説明が必要でしょう.この書き方はディレクティブというものでLaTeXにおけるenvironmentと同じようなものです.例えば上記のコードはLaTeX風に書くと

\begin{toctree}[maxdepth=2]

\end{toctree}

となります.オプションは他にも色々ありますがここでは省略します.rstにはディレクティブが終わる場所が明示されていないようにも見えますが,ここもインデントを終了することで\end{toctree}を示します.

ディレクティブの文法について説明しておきます.topicというディレクティブを使うとしましょう.まず,文頭に「..」と書き,半角スペースを一つ.更に「:」を2つ書き改行し,ディレクティブの中に入れるものはインデントして書きます.

それではtoctreeディレクティブを使ってみましょう.toctreeは他のrstファイルを自分のファイルの子要素に指定するものです.今,index.rstがある階層にいるものとします.

子要素にするドキュメントを入れるファイルを作り,その中に子文書child1.rstとchild2.rstを作ります.

cd source
mkdir children
cd children
echo -e "これは子文書1です\n=========================================" > child1.rst
echo -e "これは子文書2です\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`

は入門には早いという理由で今回は触れないことにします.文書には索引があるわけで,その索引へのリンクを入れることになりますが,索引ファイルは別で作らなければならないのでこれだけでは使えません.邪魔であれば消しても良いと思います.

おわりに

ここまでで,普通の文書を作る上での最低限必要な知識が得られたと思います.後は日本語に翻訳された素晴らしいドキュメントを見れば殆どのことは解決すると思います.

大学教授が授業ページを作っていたりしますが,大抵HTML直書きで読みにくいものです.それもSphinxを使えば解決すると思います.知り合いに聴いてみてもSphinxの知名度は高くないようで,この記事が少しでもSphinxの存在の周知に貢献できていれば幸いです.