Sphinxで階層構造のサイドメニューを利用する（HTMLサイト）
Sphinxで階層構造のサイドメニューを試してみました。
2023.09.25
この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
Sphinxは、文章作成ツールのひとつです。 ソースコードの関数コメントからAPIドキュメントを作成したり、reStructuredText形式のテキストドキュメントから、HTMLファイルを作成できます。 拡張機能を利用すれば、Markdown形式のテキストドキュメントも扱えます。
今回は、HTMLサイトで階層構造のサイドメニューを試してみます。
おすすめの方
- Sphinxについて知りたい方
- Sphinxで階層構造のサイドメニューを利用したい方（HTMLサイト）
Sphinxを使う準備をする
Sphinxを導入する
公式の手順に従って、導入します。
適当なプロジェクトを作成する
公式の手順に従って、適当なプロジェクトを作成します。
sphinx-quickstart docs
ビルドする
HTMLサイトをビルドします。
cd docs
make html
ビルド後は、下記のファイルを開いて、確認します。
open build/html/index.html
階層構造のサイドメニューを利用する
サイドメニューの構成を決める
適当にサイドメニューの構成を決めます。今回は次のようにしてみます。
- 北海道
- 札幌市
- 釧路市
- 旭川市
- 東京都
- 千代田区
- 品川区
- 八王子市
- 福岡県
- 北九州市
rstファイルを作成する
docs/sourceに下記のファイルを作成します。
- hokkaido.rst
- sapporo.rst
- kusiro.rst
- asahikawa.rst
- toukyo.rst
- chiyoda.rst
- shinagawa.rst
- hachioji.rst
- fukuoka.rst
- kitakyushu.rst
rstファイルに toctree を設定する
それぞれ上位となるrstファイルに toctree を記載します。
index.rst
Welcome to test-blog's documentation!
=====================================
.. toctree::
:maxdepth: 2
:caption: Contents:
hokkaido
toukyo
fukuoka
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
hokkaido.rst
北海道
=====================================
.. toctree::
:maxdepth: 2
:caption: Contents:
sapporo
kusiro
asahikawa
sapporo.rst
札幌市
=====================================
kusiro.rst
釧路市
=====================================
asahikawa.rst
旭川市
=====================================
toukyo.rst
東京都
=====================================
.. toctree::
:maxdepth: 2
:caption: Contents:
chiyoda
shinagawa
hachioji
chiyoda.rst
千代田区
=====================================
shinagawa.rst
品川区
=====================================
hachioji.rst
八王子市
=====================================
fukuoka.rst
福岡県
=====================================
.. toctree::
:maxdepth: 2
:caption: Contents:
kitakyushu
kitakyushu.rst
北九州市
=====================================
ビルドして生成されたHTMLファイルを確認する
make html
階層構造のメニューができました。
それぞれのページに移動した際のサイドメニューは、下記となっています。
別のテーマでも試してみる
次のテーマを導入し、ビルドしてみました。
階層構造のメニューになりました。
さいごに
Sphinxで階層構造のサイドメニューにしてみました。 どなたかの参考になれば幸いです。
