Sphinxで階層構造のHTMLドキュメントを作成する方法

2023年12月25日

本記事の主旨

Sphinxで、サブカラムから記事を選択できる階層構造のHTMLドキュメントを作る方法について記す。

本記事の目的

本記事の目的を以下に記す。

• 一番簡潔な方法で階層構造のHTMLドキュメントを作成する方法を示す。
  • ほかに方法があっても、わかりにくければ解説しない。

本記事の背景

Sphinxで作成したサブカラムからページが見れる階層構造のHTMLドキュメントはインターネット上に多い。

しかし、そのようなサイトやドキュメントの作成方法が書かれているサイトを見かけない。

そのため本記事で解説する。

サンプルコードURL

本記事で用いるサンプルは、筆者のオリジナルコードである。

noindexタグをヘッダーに後付けして、以下のURLで公開している。

本記事で用いたサンプルコードのディレクトリ構造を以下に示す。

C言語等と同様、「//」の右にコメントを書いた。

E:.
│  conf.py    //設定用ファイル
│  index.rst    //ルートURLのHTMLを記述するファイル
│  ヘルプ.rst    //ヘルプページのファイル
│  概要.rst    //概要ページのファイル
│
├─ツール
│      index.rst    //この階層のURLのHTMLを記述するファイル
│      VSCode.rst    //VSCode説明ページのファイル
│      WinMerge.rst    //WinMerge説明ページのファイル
│
└─議事録・定例会
    ├─内部定例議事録    //内部定例議事録を入れておくフォルダ
    │      20231116_内部定例議事録.rst
    │      20231123_内部定例議事録.rst
    │
    └─顧客定例議事録    //顧客定例議事録を入れておくフォルダ
            20231113_顧客定例議事録.rst
            20231120_顧客定例議事録.rst

階層構造の構築

デフォルトの組み込みテーマ「alabaster」では、サブカラムが階層構造にならない。

したがって、組み込みテーマ「agogo」を用いて説明する。

以下に階層構造のHTMLドキュメントの構築について記す。

サブカラムに各タイトルを配置

サブカラムには各タイトルを配置できる。下図右赤枠部分参照。

画面遷移

サブカラムにある各タイトルをクリックすると、そのタイトルの記事に飛ぶ。

サブカラム上では、タイトルの下に見出しが並列して表示される。下図右赤枠部分参照。

コード追加

下図右赤枠部分について実際のコードを用いて説明する。

conf.pyと同じ階層にあるトップページ用のindex.rstに、以下のコードを書き加えた。

.. toctree::
   :hidden:
   :caption: 概要
   
   概要.rst

.. toctree::
   :hidden:
   :caption: 内部定例
   :glob:
   
   議事録・定例会/内部定例議事録/*

.. toctree::
   :hidden:
   :caption: 顧客定例
   :glob:

   議事録・定例会/顧客定例議事録/*

.. toctree::
   :hidden:
   :caption: お役立ちツール
   
   ツール/index.rst
   
.. toctree::
   :hidden:
   :caption: ヘルプ
   
   ヘルプ.rst

ここで追加したコードには並べ方に以下の二つのタイプがある。

1. reStructuredTextファイルパス名を並べて書く。

.. toctree::
   :hidden:
   :caption: 概要
   
   概要.rst

このとき、並べて書かれたreStructuredTextファイルそれぞれの最初に書かれている見出しが箇条書きで表示される。ここで、上記のように:hidden:オプションを使用すると非表示にできる。

箇条書きは:maxdepth:オプションで指定した深さまでの見出しが表示される。ここで、:maxdepth:オプションを指定しない場合は2つ目までの深さの見出しを表示する。

:caption:オプションは、サブカラムの見出しを指定する。ファイル内の箇条書きの説明としては黒字で書かれる。

具体的には、以下の図のようになる。このとき概要.rst内には、見出し「概要」の中に見出し「プロジェクト名」と見出し「納期」が入っている。

2. reStructuredTextファイルパス名を一括指定して書く。

.. toctree::
   :hidden:
   :caption: 内部定例
   :glob:
   
   議事録・定例会/内部定例議事録/*

:glob:オプションを使用して、正規表現でreStructuredTextファイルパス名を書く。ここで「*」は、その部分の文字列を問わないことを意味する。

サブカラムでタイトルを開いたときに見出しの下にタイトルを配置

サブカラムの各タイトルを開くと見出しが表示されるが、その下にタイトルを表示できる。下図右赤枠部分参照。

画面遷移

タイトルの記事を開いた後、サブカラム上ではそのタイトルの下に見出しが並列して表示される。

このとき同時に、その見出しの下にタイトルを配置する。

下図右赤枠部分について実際のコードを用いて説明する。

コード追加

トップページのindex.rstで指定した、「ツール/index.rst」に以下のコードを書き加えた。

.. toctree::
   :maxdepth: 1
   :glob:
   
   *

階層構造のHTML作成

階層構造のHTML作成について以下に示す。

ビルド方法

make.batファイルがある階層で「.\make html」コマンドを打つとビルドできる。

ビルド後のディレクトリの階層構造

本記事で用いたサンプルソースで、ビルド後のhtmlのディレクトリ構造を以下に示す。

E:.
│  .buildinfo
│  genindex.html
│  index.html
│  objects.inv
│  search.html
│  searchindex.js
│  ヘルプ.html
│  概要.html
│
├─_sources
│  │  index.rst.txt
│  │  ヘルプ.rst.txt
│  │  概要.rst.txt
│  │
│  ├─ツール
│  │      index.rst.txt
│  │      VSCode.rst.txt
│  │      WinMerge.rst.txt
│  │
│  └─議事録・定例会
│      ├─内部定例議事録
│      │      20231116_内部定例議事録.rst.txt
│      │      20231123_内部定例議事録.rst.txt
│      │
│      └─顧客定例議事録
│              20231113_顧客定例議事録.rst.txt
│              20231120_顧客定例議事録.rst.txt
│
├─_static
│      agogo.css
│      basic.css
│      bgfooter.png
│      bgtop.png
│      doctools.js
│      documentation_options.js
│      file.png
│      language_data.js
│      minus.png
│      plus.png
│      pygments.css
│      searchtools.js
│      sphinx_highlight.js
│      translations.js
│
├─ツール
│      index.html
│      VSCode.html
│      WinMerge.html
│
└─議事録・定例会
    ├─内部定例議事録
    │      20231116_内部定例議事録.html
    │      20231123_内部定例議事録.html
    │
    └─顧客定例議事録
            20231113_顧客定例議事録.html
            20231120_顧客定例議事録.html

conf.pyと同じ階層にあるindex.rstが、トップページのindex.htmlになる。reStructuredTextファイルは、トップページのindex.rstからの相対パスと同じ位置関係で、同名でHTMLにビルドされる。

toctreeの表示・非表示にかかわらず、そのページからtoctreeディレクティブでたどることができる。reStructuredTextファイルや、そのファイルの先々に更にたどっていくことができるreStructuredTextファイルのみがHTMLにビルドできる。

広告

Sphinxのインストールやビルドについて書かれた本。初心者向けで基本的なことのみ書かれている。

reStructuredTextの使い方が詳しく書かれているため、reStructuredTextを使用するには一番参考になる本。