RTDしたい(sphinx_rtd_theme

$ pip3 install sphinx_rtd_theme

sphinx_rtd_themeのtheme.confを眺めてみます。 これも元のテーマはbasicとなっていることが分かりました。

プロジェクトに追加したい

1$ cd プロジェクト名
2$ poetry add --group=docs sphinx
3$ poetry add --group=docs sphinx_rtd_theme
4$ poetry add --group=docs myst_parser
5$ sphinx-quickstart docs
6$ code docs/conf.py

poetryを使ってプロジェクトに追加する手順を書き出してみました。 ドキュメント関係のパッケージなので--group=docsに分類しています。

sphinx_rtd_themeはMySTと併用できます。 必要はパッケージ(sphinx / sphinx_rtd_theme / myst_parser)を追加、 docsにドキュメント用ディレクトリを作成、 docs/conf.pyを開いて、以下の設定を追記します。

テーマを使いたい

 1import sphinx_rtd_theme
 2
 3extensions = [
 4    ...
 5    "sphinx_rtd_theme",
 6    "myst_parser",
 7    ...
 8]
 9
10html_theme = "sphinx_rtd_theme"

拡張(extensions)一覧にパッケージ名を追加します。 また、html_themeをパッケージ名に変更します。

テーマのオプションを設定する

1html_theme_options = {
2    "analytics_id": "G-XXXXXXXXXX",  #  Provided by Google in your dashboard
3    "prev_next_buttons_location": "both",
4    "style_external_links": True,
5}

僕が必要だと思ったオプションを設定しました。 設定可能なオプションとその説明は公式ドキュメントのConfigurationを参照してください。

Google Analyticsしたい

1html_theme_options = {
2    "analytics_id": "G-xxxxxxxx",
3    "analytics_anonymize_ip": False,
4}

Read the Docsのドキュメントを参照すると、Configurationのページにオプションの設定方法が書かれていました。