ドキュメントを構造化する

まずはドキュメントを構造化する際に骨となる toctree ディレクティブの説明です。 とても重要なディレクティブですので必ず読んで下さい。

ドキュメントを構造化する

ドキュメントを作成する際は、大抵、大項目をいくつか挙げ、その下に紐付く中項目、小項目をぶら下げる ツリー構造 で考える事が多いのではないでしょうか？ ツリー構造 であれば見通しがよくなりドキュメントの作成を進めやすいですよね。

Sphinxの場合は ツリー構造 にする方法が2つあります。

1. toctree ディレクティブ

• index.rst と同じディレクトリ階層に2つのreSTファイルを置くと仮定します。

  1. first.rst:

     1つ目のファイル
     ================
     * これは1つ目のファイルです。
     

  2. second.rst:

     2つ目のファイル
     ================
     * これは2つ目のファイルです。
     

  これらのファイルを index.rst に読み込ませるには下記のように記述します。

  .. toctree::
  
     first
     second
  

  html化すると このようになるはずです。

2. ディレクトリ管理

• 単純にreSTファイルをディレクトリに小分けして格納するだけです。

  .. toctree::
  
     unyo/tejun01
     unyo/tejun02
     unyo/tejun03
     kochiku/network
     kochiku/kanshi
     kochiku/server
  

  例では index.rst と同じ階層に unyo , kochiku というディレクトリを作成し、それぞれのディレクトリ配下にreSTファイルを作成してあります。

  • unyoディレクトリ
    • tejun01.rst
    • tejun02.rst
    • tejun03.rst
  • kochikuディレクトリ
    • network.rst
    • kanshi.rst
    • server.rst

  ※例は省きます