3. 具体的な文章作成の例

Sphinx での文章ファイルは単なるテキストファイルであるが、様々なルールの 下で記述されていると文章の修飾を行うことができる。この文章フォーマットを Restructured text と呼ばれる。

3.1. 文章のレベル

文章の見出しのレベルは下記のように罫線を挿入することで分けることができる.

サンプル

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

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

レベル3
~~~~~~~~~~~

レベル4
===========
_images/level.png

実際には上のようになります。

3.2. ディレクティブについて

テーブルや図、数式を入れたり、重要点などを強調するような文章を修飾する 機能は下記で示すディレクティブと呼ばれる記述方法を用いる。

ディレクティブの書き方

+-------+---------------------------------------------------+
| ".. " | ディレクティブタイプ "::" ディレクティブブロック  |
+-------+                                                   |
        |                                                   |
        +---------------------------------------------------+

ブロック図などもディレクティブを用いれば挿入することができる。

例えば上のような図を挿入する場合、

.. blockdiag::

   blockdiag {
     // orientation = portrait
   'A' -> 'B' -> 'C';
   }

縦方向にする場合は縦方向にする場合は　//orientation = portrait を外す。

似たようなことは graphviz でもできる。

digraph graph_name { graph [rankdir = LR]; "不活性" -> "活性" [ label = "可逆", //エッジラベル taillabel = "解離", //エッジの始端にラベルをつける headlabel = "会合", dir = both, //エッジの矢印を指定する ]; }

これは、:

.. graphviz::

    digraph graph_name {

    graph [rankdir = LR];           //　横方向へ展開

    "不活性" -> "活性" [
        label = "可逆",            //エッジラベル
        taillabel = "解離",       //エッジの始端にラベルをつける
        headlabel = "会合",
        dir = both,               //エッジの矢印を指定する
    ];
    }

で書ける。 graphviz では縦方向がデフォルトで横方向にする場合は、

graph [rankdir = LR];

を入れている。

ディレクティブでは、ソースコードを読み込んで表示することも可能である。

重要

ディレクティブなどを使用する際、間違った文章を入力すると（多くはインテンドや改行が多い）エラーコードは出力されない。 エラー部分は単に抜けてしまうので、最終出力と Restructured text の中身が一致していることを常に確認する。

3.3. toctree

toctree とは複数のファイルをひとつのドキュメントにまとめられる機能である。 長い文章や複数の人間で文章を仕上げる時には有効である。

indexの中身

例

.. toctree::
   :numbered:

   goto
   tsuka

これを実行すると二人のファイルが合体しひとつのドキュメントになる。 :numbered: によって章、節などが自動的にナンバリングされる。 jupyter-notebook との連携をセットアップしておけば、 toctree の下に:file:*.ipynb を入れることも可能。 その際は拡張子は記述しない。