はじめに
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 | 3.10.0 |
| Sphinx | 4.4.0 |
| Furo | 2021.10.9 |
SphinxとFuroテーマのインストール
Pythonは既にインストールされているものとして、SphinxとFuroテーマをインストールします。
Condaとpipのどちらでもインストール可能ですが、2022年2月27日現在、Conda側のバージョンは少し古いです（最新バージョンはConda側でv2021.10.9, PyPI側でv2022.2.23）。
Conda環境では以下を実行します。-cオプションによって、インストール元のチャンネルを指定します。
|
|
pipの場合は以下を実行します。
|
|
プロジェクトテンプレートの作成
適当な空フォルダを作成し、sphinx-quickstartコマンドを実行してプロジェクトテンプレートを作成します。詳細は以下の記事を参考にしてください。
テーマの変更とHTMLファイルのビルド
作成したプロジェクトの設定ファイルconf.pyを開き、57行目にあるhtml_themeをalabasterからfuroに変更します。
|
|
変更後、以下のコマンドを実行してHTMLファイルをビルドします。
|
|
build/html/index.htmlをウェブブラウザで開くと、以下の通りFuroテーマが適用されたことを確認できます。
