はじめに
sphinx は、マークダウンっぽい文法（reStructuredText記法）で書かれたテキストファイルを HTML, Word, PDF, ePub 等に変換するためのツールです。たとえば、私が書いた PHP Extension 開発入門のページも sphinx で作られています。
これまでは、sudo dnf install python3-sphinx で普通に満足していたんですが、これだと本家に大きく遅れたバージョンしか入らないことに気づいてしまったので、新しめのバージョンを入れてみるテストです。
前提事項
OS: Alma Linux 8.x(CentOS8 互換）
pyenv + venv 環境が作成されていること。以下のような環境を想定しています。
(venv) vagrant@host:~$ pyenv versions
system
* 3.11.4 (set by /home/vagrant/.python-version)
(venv) vagrant@host:~$ pip3 list
Package Version
---------- -------
pip 23.1.2
setuptools 65.5.0
Python 環境の作成方法は pyenv+venvによるpython実行環境の設定 を参照してください。
sphinx のインストール
(venv) vagrant@host:~$ pip3 install sphinx
(venv) vagrant@host:~$ pip3 install sphinx_rtd_theme
(venv) vagrant@host:~$ sphinx-quickstart --version
sphinx-quickstart 7.0.1
ドキュメントのビルド環境の作成
いつの間にかメッセージが日本語化されていたので、メッセージに従って設定します。
(venv) $ mkdir docs
(venv) $ cd docs
(venv) $ sphinx-quickstart
Sphinx 7.0.1 クイックスタートユーティリティへようこそ。
（中略）
ファイル /home/vagrant/docs/conf.py を作成しています。
ファイル /home/vagrant/docs/index.rst を作成しています。
ファイル /home/vagrant/docs/Makefile を作成しています。
ファイル /home/vagrant/docs/make.bat を作成しています。
終了：初期ディレクトリ構造が作成されました。
マスターファイル /home/vagrant/docs/source/index.rst を作成して
他のドキュメントソースファイルを作成します。次のように Makefile を使ってドキュメントを作成します。
make builder
"builder" はサポートされているビルダーの 1 つです。 例: html, latex, または linkcheck。
Read the Docs テンプレートの適用
(venv) $ vi conf.py
変更前）html_theme = 'alabaster'
変更後）html_theme = 'sphinx_rtd_theme'
(venv) $ make html
Sphinx v7.0.1 を実行中
（中略）
ビルド 成功.
HTMLページは_build/htmlにあります。
終わりに
Sphinx の文法は、逆引き辞典あたりを参照していただければと思います。ちなみに *.rst は Github でもサポートされているので、ソースファイルをそのまま push すれば Github 上でいい感じに表示されます。
以上です。Have fun!!
