让 sphinx 使用 setup.py 中的版本

Posted 2023-03-07

【中文标题】让 sphinx 使用 setup.py 中的版本

【英文标题】：Let sphinx use version from setup.py

【发布时间】：2014-11-26 07:44:08

【问题描述】：

如果我选择sphinx-quickstart，我会被问及项目的版本。

我想避免我的项目版本有两个位置。

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

【问题讨论】：

那么，是否有任何答案对您有用？如果是这样，请接受相应的答案。如果不是，那是什么问题？

感谢您的提问。我对这个话题并不着急。我想要一个规范的答案。我会在 dist-sig 上提问：python.org/community/sigs/current/distutils-sig

相关：packaging.python.org/en/latest/single_source_version.html

【参考方案1】：

最简单（可能也是最干净）的方法是为***包的__init__.py 定义__version__，然后导入该包并读取setup.py 和Sphinx 项目的conf.py 中的版本.

假设您的项目名为myproject。

将您当前的版本从setup.py 中移出，并将其改为myproject/__init__.py 中的变量：

myproject/__init__.py：

# import foo
# ...

__version__ = '1.5'

在项目的setup.py 中导入myproject，并将硬编码的版本替换为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 中定义的配置值。

【讨论】：

在另一个 SO question 中已经指出，如果您在 myproject/__init__.py 中导入一些依赖项，然后在 setup.py 中执行 from myproject import __version__，用户将无法安装没有先安装依赖包的包：***.com/questions/2058802/…

我们也遇到了第三方导入的问题，并通过引入一个仅包含元信息的单独包来解决它。看看这个答案：***.com/a/52381178/1600678

【参考方案2】：

你可以看看bumpversion模块：

“一个小型命令行工具，通过以正确的增量更新源代码中的所有版本字符串来简化软件发布”

您可以使用配置文件.bumpversion.cfg 进行复杂的多文件操作。

【参考方案3】：

也许一个更干净的选择是从setup.py 命令实际构建狮身人面像，如http://www.sphinx-doc.org/en/master/setuptools.html 中所述：

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 成为版本号的单一来源 避免不必要地从项目文件夹中制作包

【讨论】：

您必须手动安装 Sphinx 才能使 setup.py 正常工作。所以你不能再使用pip3 -e .了。

@Pierre.Sassoulas 这是一个非常好的观点，感谢您指出这一点。但是，如果使用setup.cfg 或pyproject.toml，这个问题可能会消失，对吧？ Sphinx 文档有 a section 关于它。

【参考方案4】：

另一种方法是将setuptools_scm 集成到您的项目中。这样你就可以

from setuptools_scm import get_version

version = get_version()

在你的conf.py