いつも記事を読んでいただきありがとうございます！
モブエンジニア（@mob-engineer)です！

今回はPython製のドキュメント生成ツールSphinxでいい感じのWebページを生成するためのナレッジを共有したいと思います👍

目次

項番	タイトル
1	本記事を役立ててもらいたい方
2	記事内で取り上げること・取り上げないこと
3	SphinxでWebページを作成してみる！
4	テーマをsphinx-rtd-themeに変えてみたが......
5	右余白をいい感じで使えるようにする
6	まとめ
7	参考サイト

本記事を役立ててもらいたい方

SphinxでWebページを作成している方
sphinx-rtd-themeを利用している方

記事内で取り上げること・取り上げないこと

記事内で取り上げること

Sphinx、sphinx-rtd-themeのインストール方法
sphinx-rtd-themeの右余白利用方法
よく使うRSTファイル記載ルール紹介

記事内で取り上げないこと

Sphinx運用のベストプラクティス
CI/CDを含めたSphixn環境
その他（カスタムCSSを用いた柔軟なデザイン変更など）

SphinxでWebページを作成してみる！

Sphinxを用いてWebページの作成を行っていきます。

作業環境へSphinxをインストール

あらかじめ、作業環境で「Python」および「pip」を利用可能にしておいてください。

作業環境

$ pip install sphinx

Sphinxインストール後バージョン確認

作業環境

$ sphinx-build --version
>sphinx-build <バージョン番号>

sphinx-rtd-themeインストール

作業環境

$ pip install sphinx-rtd-theme

Sphinxプロジェクト作成

プロジェクト作成

作業環境

$ sphinx-quickstart docs

実行後、応答文が表示されるため以下のとおり入力

作業環境

Welcome to the Sphinx 7.4.7 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: docs

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
**> Separate source and build directories (y/n) [n]: y 　※yを入力（sourceとbuildファイル分割）

The project name will occur in several places in the built documentation.
> Project name: test-project　※プロジェクト名を入力
> Author name(s): test-project　※作者名を入力
> Project release []: 1.0.0　※リリース番号を入力

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: ja　※言語を入力

Creating file /home/ec2-user/sphinx-test/docs/source/conf.py.
Creating file /home/ec2-user/sphinx-test/docs/source/index.rst.
Creating file /home/ec2-user/sphinx-test/docs/Makefile.
Creating file /home/ec2-user/sphinx-test/docs/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /home/ec2-user/sphinx-test/docs/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

上記情報は、プロジェクト作成後生成されるConfigファイル（conf.py）で修正可能です。

現在のディレクトリ構成

index.rstがトップページ用のソースコードとなります

index.rstを書き換えよう

以下のとおりindex.rstファイルを書き換えました。

RSTファイルの記載方法は以下を参照してください
https://docutils.sourceforge.io/docs/ref/rst/directives.html#top

Sphinx-build実行

作業環境

$ sphinx-build -M html docs/source/ docs/build/

buildディレクトリ配下にHTMLファイルが生成されます。
build > html > index.htmlをWebブラウザ上で開いてください。

VSCodeの場合「Live Server」を利用すれば、「index.html→右クリック→Open With Live Server」をクリックすることでWebブラウザ上に表示できます。

ブラウザ上での表示イメージ

sphinx-rtd-themeに変更する

conf.py内の以下内容の次のように書き換える

conf.py

import sphinx_rtd_theme
extensions = ['sphinx-rtd-theme']
html_theme = 'sphinx-rtd-theme'

Sphinx-build実行

作業環境

$ sphinx-build -M html docs/source/ docs/build/

テーマをsphinx-rtd-themeに変えてみたが......

右側余白も利用したいが、グレーアウトしている......
カスタムCSSの機能を利用していい感じに右余白を利用できるようにしよう

右余白をいい感じで使えるようにする

source > _staticディレクトリ配下に、以下custom.cssファイルを作成

ustom.css

.wy-nav-content {
    max-width: 1600px;
}

conf.pyに以下設定を追加

conf.py

html_css_files = [
    'custom.css',
]

Sphinx-build実行

作業環境

$ sphinx-build -M html docs/source/ docs/build/

ブラウザ画面

いい感じで右余白も利用できるようになった👍

まとめ

今回はSphinxに関するナレッジを記事にしました。
ハンズオン系の記事執筆は初めてだったため、慣れないところもありましたが、とりあえずまとめられてよかったと思います。個人的にSphinxは「お手軽Webサイト」を作成するという視点では、（現状）最強のツールだと考えています。引き続き、Sphinx関連のハンズオン記事も執筆したいと思います。

参考サイト

Sphinx の sphinx_rtd_theme をカスタマイズする
 reST を書かずに autodoc だけで Sphinx する
 Sphinx公式ドキュメント

最後まで記事を読んでいただきありがとうございます。
読んでみて、「良かった」とおもったらハートボタンとストックを行っていただければ、作者が喜びます！