在 setup.py 上使用 sphinx BuildDoc

Question

我正在选择 setup.py 中的 python 项目：

from sphinx.setup_command import BuildDoc

commands["build_sphinx"] = BuildDoc
cmd_opts["build_sphinx"] = {
    "project": ("setup.py", NAME),
    "version": ("setup.py", about["__version__"]),
    "release": ("setup.py", about["__version__"]),
    "source_dir": ("setup.py", "docs"),
}

这是从 setuptools 传递给 setup() 现在这给了我一个导入错误，因为它找不到模块。 从 sphinx 文档我们有：

# this is only necessary when not using setuptools/distribute from sphinx.setup_command import BuildDoc

http://code.nabla.net/doc/sphinx/api/sphinx/setup_command/sphinx.setup_command.BuildDoc.html

所以我的问题是我是否可以从某个地方导入这个 BuildDoc，或者我应该像文档建议的那样以另一种方式使用 setuptools，如果可以，我该怎么做？

PS：我还会在项目中添加诗歌，所以如果有关于狮身人面像的诗歌，我可能会想要那个

我试着寻找 BuildDoc 导入

编辑：我现在知道 sphinx 与 setuptools 的集成在 sphinx 7.0.0 中被破坏了，还有办法集成吗？

Answer 1

是的，您仍然可以将 Sphinx 与 setuptools 集成，即使它在 Sphinx 7.0.0 中已被弃用。为此，您可以使用 setuptools_sphinx 包，它提供了一个 setuptools 扩展，您可以在安装过程中使用它来构建 Sphinx 文档。

这是一个如何在 setup.py 中使用 setuptools_sphinx 的示例：

from setuptools import setup
from setuptools_sphinx import SphinxBuild

setup(
    name='your_package',
    # Other setup() parameters...
    cmdclass={
        'build_sphinx': SphinxBuild,
    },
    # Optional Sphinx options...
    sphinx={
        'source_dir': 'docs',
        'build_dir': 'docs/_build',
        'config_dir': 'docs',
        'project': 'Your Project Name',
        'version': '0.1',
        'release': '0.1.0',
    },
)

此代码使用 setup() 函数中的 cmdclass 参数向 setuptools 注册一个 SphinxBuild 命令。它还使用 sphinx 参数提供 Sphinx 选项。

然后您可以通过运行 python setup.py build_sphinx 使用 setuptools 构建您的文档。生成的 HTML 文档将位于 docs/_build/html 目录中。

如果您正在使用 Poetry，则可以使用 poetry-setup 包将 setuptools_sphinx 与 Poetry 集成。以下是如何使用它的示例：

from setuptools_sphinx import SphinxBuild
from poetry_setup import setup

setup(
    name='your_package',
    # Other setup() parameters...
    cmdclass={
        'build_sphinx': SphinxBuild,
    },
    # Optional Sphinx options...
    sphinx={
        'source_dir': 'docs',
        'build_dir': 'docs/_build',
        'config_dir': 'docs',
        'project': 'Your Project Name',
        'version': '0.1',
        'release': '0.1.0',
    },
)

此代码与前面的示例类似，但使用 poetry_setup.setup() 而不是 setuptools.setup() 向 Poetry 注册 SphinxBuild 命令。然后，您可以使用 poetry run python setup.py build_sphinx.

构建您的文档