让sphinx使用setup.py中的版本

Question

如果我这样做,sphinx-quickstart我会被问及项目的版本.

我想避免为我的项目版本提供两个位置.

如何在python包装世界中做到这一点？

Answer 1

最简单的(也许干净的)方法是定义__version__为__init__.py您的顶级包,然后导入包和阅读两个版本,setup.py和你的狮身人面像项目conf.py.

那么就说你的项目被调用了myproject.

移出当前版本setup.py,并将其变为变量myproject/__init__.py:

myproject/__init__.py:

# import foo
# ...

__version__ = '1.5'

myproject在项目中导入setup.py,并将硬编码版本替换为myproject.__version__:

setup.py:

from setuptools import setup
from myproject import __version__


project = "myproject"

setup(
    name=project,
    version=__version__,
    # ...
)

在你的Sphinx项目中conf.py,做同样的事情.所以编辑conf.py沿这些行生成的:

docs/conf.py:

from myproject import __version__

# ...

# The short X.Y version.
version = __version__
# The full version, including alpha/beta/rc tags.
release = version

有关这样做的库的示例,请查看requests模块(__init__.py| setup.py| conf.py).

这将处理使用项目版本的自动生成的文本(如指向文档首页的链接).如果要在特定自定义位置使用您的版本,可以使用该rst_epilog指令动态插入在中定义的配置值conf.py.

Answer 2

也许更干净的选择是setup.py按照http://www.sphinx-doc.org/en/master/setuptools.html中的描述从命令实际构建sphinx ：

setup.py

# this is only necessary when not using setuptools/distribute
from sphinx.setup_command import BuildDoc
cmdclass = {'build_sphinx': BuildDoc}

name = 'My project'
version = '1.2'
release = '1.2.0'
setup(
    name=name,
    author='Bernard Montgomery',
    version=release,
    cmdclass=cmdclass,
    # these are optional and override conf.py settings
    command_options={
        'build_sphinx': {
            'project': ('setup.py', name),
            'version': ('setup.py', version),
            'release': ('setup.py', release),
            'source_dir': ('setup.py', 'doc')}},
)

然后使用

$ python setup.py build_sphinx

优点：

• 使setup.py的版本号的单一来源
• 避免不必要地将软件包从项目文件夹中移出

Answer 3

从 pyproject.toml 中提取信息

如果您使用 a ，pyproject.toml您也可以在conf.pywith tomli中解析它，或者在使用python ^3.11时使用等效的tomllib。像这样，您可以从 sphinx 文档配置中 提取信息并使用它。
pyproject.toml

这是一个使用 的简短不完整示例tomli，假设conf.py
位于<project-root>/docs/source/conf.py：

# conf.py

import tomli
with open("../../pyproject.toml", "rb") as f:
    toml = tomli.load(f)

# -- Project information -----------------------------------------------------

pyproject = toml["tool"]["poetry"]

project = pyproject["name"]
version = pyproject["version"]
release = pyproject["version"]

copyright = ...
author = ...

# and the rest of the configuration