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

まずはドキュメントを構造化する際に骨となる 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

    ※例は省きます