動機
PEP 621 や PEP 631 にあるように、Python を使うプロジェクトの設定は pyproject.toml に記載することが求められている。
poetry は pyproject.toml を自動生成し、インストールしたパッケージ情報を（requirements.txt を使うこと無く）pyproject.toml に記載してくれる。
また sphinx-pyproject は pyproject.toml を自動的に読み取るので、
Sphinx の conf.py から sphinx-pyproject の SphinxConfig を呼び出す事で、pyproject.toml を変更するだけでドキュメントを変更できるようになる。
このことによって、バージョン番号を上げる時など、pyproject.toml の一箇所を変更するだけで、パッケージのバージョン番号・ドキュメントのバージョン番号の両方を一度に変更でき・・・るように思ってしまう。
しかしそう上手く問屋は卸さない。
poetry は基本的な必須情報（name, version, description, authors）を pyproject.toml の [tool.poetry] セクションに設定してしまう。これがないと poetry が動かない。
これに対し sphinx-pyproject は、PEP に定義されているように、基本的な必須情報は [project] セクションに設定されているものとして読み込む。
（もちろん sphinx-pyproject に poetry の事情を汲み取る義理は無い）
この問題は poetry 側の問題であり、これを解決するよう issue も作られている。
しかしこの issue の議論を見る限り、この問題が解決される気配は無い。
（とても残念）
pyproject.toml に [project] と [tool.poetry] の両方を設定することが最も早い解決法だが、同じファイルであっても２箇所に同じ設定があるのは、やはりとても気持ちが悪い。
そこで sphinx-pyproject 側を修正し、無理やり [project] ではなく [tool.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 の５つの項目は [tool.poetry] から読み込む。そして authors と maintainers の２つの項目は併せて author という名前で保持される。
conf.py で設定できる項目は、www.sphinx-doc.org に全部載っている。そして項目を追加する場合でも修正する場合でも、pyproject.toml に設定を追加したり変更するだけである。
便利！！（自画自賛）