いつも記事を読んでいただきありがとうございます！
モブエンジニア（@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内の以下内容の次のように書き換える
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ファイルを作成
.wy-nav-content {
max-width: 1600px;
}
- 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公式ドキュメント
最後まで記事を読んでいただきありがとうございます。
読んでみて、「良かった」とおもったらハートボタンとストックを行っていただければ、作者が喜びます！