让 sphinx 使用 setup.py 中的版本

Question

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

我想避免我的项目版本有两个地方。

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

Answer 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中定义的配置值。

Answer 2

也许更清洁的选择是从setup.py命令实际构建 sphinx，如http://www.sphinx-doc.org/en/master/setuptools.html中所述：

安装程序.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

你可以看一下bumpversion模块：

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

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

Answer 4

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

from setuptools_scm import get_version

version = get_version()

在你的conf.py

Answer 5

这是一个简单的解决方案，讽刺的是来自setuptools_scm PyPI 页面：

# contents of docs/conf.py
from importlib.metadata import version
release = version('myproject')
# for example take major/minor
version = '.'.join(release.split('.')[:2])

以下是他们解释为什么不鼓励使用 Sphinx 的软件包：

根本原因是，Read the Docs 之类的服务有时会出于充分的理由更改工作目录，并且使用已安装的元数据可以防止在那里使用不必要的易失性数据。