Move some of your Sphinx configuration into pyproject.toml created by poetry
PEP 621 や PEP 631 にあるように、 プロジェクトの設定は pyproject.toml に記載することが求められている。
poetry は pyproject.toml を自動生成し、 インストールしたパッケージ情報を(requirements.txt を使うこと無く) pyproject.toml に記載してくれる。
また sphinx-pyproject は pyproject.toml を自動的に読み取るので、 Sphinx の conf.py に 設定することで、pyproject.toml を変更するだけで ドキュメントに記載する値を変更する事が出来る。
このことによって、バージョン番号を上げる時など、 pyproject.toml の一箇所を変更するだけで、 パッケージのバージョン番号・ドキュメントのバージョン番号の両方を 変更できる、ように思われる。
しかし poetry は
基本的な必須情報
(name, version, description, authors)を
pyproject.toml の [tool.poetry]
セクションに設定してしまう。
これに対し sphinx-pyproject は、PEP に定義されているように、
基本的な必須情報は [project]
セクションに設定されているものとして読み込む。
(もちろん sphinx-pyproject に poetry の事情を汲み取る義理は無い)
この問題は poetry 側の問題であり、これを解決するよう issue も作られている。 しかしこの issue の議論を見る限り、この問題が解決される気配は無い。
pyproject.toml に [project]
と [tool.poetry]
の両方を設定することが
最も早い解決法だが、同じファイルであっても2箇所に同じ設定があるのは、
やはりとても気持ちが悪い。
そこで sphinx-pyproject 側を修正し、
無理やり [project]
ではなく [tool.poetry]
を読み込むようにしたのが、
sphinx-pyproject-poetry である。
また sphinx-pyproject では、 authors および maintainers の項目は table として設定することを前提としている。
[[project.authors]]
name = "1st Author"
[[project.authors]]
name = "2nd Author"
しかし poetry では 1st author <1st.author@domain>
の形の配列で指定する。
[tool.poetry]
authors = ["1st Author <1st.author@domain>", "2nd Author <2nd.author@domain>"]
この問題についても sphinx-pyproject-poetry では poetry の形式を前提として、 authors および maintainers の項目を読み取る。
使い方は sphinx-pyproject と全く同じである。
# conf.py
import os
import sys
from sphinx_pyproject_poetry import SphinxConfig
sys.path.insert(0, os.path.abspath(".."))
config = SphinxConfig("../pyproject.toml", globalns=globals())
project = config.name
release = config.version
Sphinx の conf.py を上記のように修正し、
pyproject.toml の [tool.pyproject]
に項目を書くだけで、
conf.py における設定を完了することが出来る。
name, version, description, authors, maintainers の5つの項目は
[tool.poetry]
から読み込む。
そして authors と maintainers の2つの項目は併せて
author という名前で保持される。
conf.py における設定項目は、 www.sphinx-doc.org に記載されている。