JavaScriptを有効にしてください

SphinxのモダンテーマFuroを導入する

 ·   3 min read

はじめに

Python製ドキュメント生成ツールSphinxのモダンテーマFuroの導入方法をまとめました。Furoは以下の特徴を持つテーマです。

  • 3カラムのレイアウト(左側にサイトのナビゲーション、中央にコンテンツ、右側にページの目次)
  • レスポンシブレイアウトに対応
  • 目次の深さは2階層までとなっており、比較的小規模(100記事程度以下)なドキュメント向き。
  • ダークモードに切り替え可能

furo-theme

その他、Sphinxプラグインを別途導入することにより、以下の機能をFuroに追加できます。

  • MyST(Markedly Structured Text; Sphinxで使えるMarkdown方言)による記事作成。
  • OGP (Open Graph protocol) による、HTMLへのメタ情報の埋め込み
  • インラインタブ(同じアルゴリズムのソースコードを複数の言語で示したい場合に使う機能)
  • ライブローディング(自動的にHTMLをビルドする機能)
  • コードブロックの内容をクリップボードにコピーするボタン

Recommendations - Furo

環境

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オプションによって、インストール元のチャンネルを指定します。

1
2
conda install -c anaconda sphinx
conda install -c conda-forge furo

pipの場合は以下を実行します。

1
2
pip install sphinx
pip install furo

プロジェクトテンプレートの作成

適当な空フォルダを作成し、sphinx-quickstartコマンドを実行してプロジェクトテンプレートを作成します。詳細は以下の記事を参考にしてください。

Sphinxを使ったHTMLドキュメント作成

テーマの変更とHTMLファイルのビルド

作成したプロジェクトの設定ファイルconf.pyを開き、57行目にあるhtml_themealabasterからfuroに変更します。

1
html_theme = 'furo'

変更後、以下のコマンドを実行してHTMLファイルをビルドします。

1
.\make.bat html

build/html/index.htmlをウェブブラウザで開くと、以下の通りFuroテーマが適用されたことを確認できます。

index.html

参考

シェアする

Helve
WRITTEN BY
Helve
関西在住、電機メーカ勤務のエンジニア。X(旧Twitter)で新着記事を配信中です

サイト内検索