はじめに #
Python製ドキュメント生成ツールSphinxのモダンテーマFuroの導入方法をまとめました。Furoは以下の特徴を持つテーマです。
- 3カラムのレイアウト（左側にサイトのナビゲーション、中央にコンテンツ、右側にページの目次）
- レスポンシブレイアウトに対応
- 目次の深さは2階層までとなっており、比較的小規模（100記事程度以下）なドキュメント向き。
- ダークモードに切り替え可能
その他、Sphinxプラグインを別途導入することにより、以下の機能をFuroに追加できます。
- MyST（Markedly Structured Text; Sphinxで使えるMarkdown方言）による記事作成。
- OGP (Open Graph protocol) による、HTMLへのメタ情報の埋め込み
- インラインタブ（同じアルゴリズムのソースコードを複数の言語で示したい場合に使う機能）
- ライブローディング（自動的にHTMLをビルドする機能）
- コードブロックの内容をクリップボードにコピーするボタン
リンク
環境 #
OSはWindows 10 Home Ver. 21H1です。
- Python v3.10.0
- Sphinx v4.4.0
- Furo v2021.10.9
SphinxとFuroテーマのインストール #
Pythonは既にインストールされているものとして、SphinxとFuroテーマをインストールします。
Condaとpipのどちらでもインストール可能ですが、2022年2月27日現在、Conda側のバージョンは少し古いです（最新バージョンはConda側でv2021.10.9, PyPI側でv2022.2.23）。
Conda環境では以下を実行します。-cオプションによって、インストール元のチャンネルを指定します。
conda install -c anaconda sphinx
conda install -c conda-forge furo
pipの場合は以下を実行します。
pip install sphinx
pip install furo
プロジェクトテンプレートの作成 #
適当な空フォルダを作成し、sphinx-quickstartコマンドを実行してプロジェクトテンプレートを作成します。詳細は以下の記事を参考にしてください。
テーマの変更とHTMLファイルのビルド #
作成したプロジェクトの設定ファイルconf.pyを開き、57行目にあるhtml_themeをalabasterからfuroに変更します。
html_theme = 'furo'
変更後、以下のコマンドを実行してHTMLファイルをビルドします。
.\make.bat html
build/html/index.htmlをウェブブラウザで開くと、以下の通りFuroテーマが適用されたことを確認できます。
