Sphinx 7.0.0后setuptools集成BuildDoc报错及替代方案咨询

1. 是否还能导入BuildDoc？ #

不行。Sphinx 7.0.0正式弃用了与setuptools的内置集成，sphinx.setup_command模块已被移除，直接导入BuildDoc会触发导入错误，这是官方有意推行的变更，不再支持该用法。

2. setuptools集成的替代方案 #

如果想继续通过setuptools管理文档构建，有两种可行方式：

方式一：解耦文档构建与setuptools #

直接使用Sphinx原生命令sphinx-build，完全脱离setuptools的cmdclass配置：

• 在项目根目录添加Makefile（Windows可改用批处理文件），示例内容：

  html:
      sphinx-build -b html docs/source docs/build/html
  

• 或者在pyproject.toml的[project.scripts]中添加快捷命令：

  [project.scripts]
  build-docs = "sh:sphinx-build -b html docs/source docs/build/html"
  

  执行python -m pip install -e .后，即可用build-docs命令一键构建文档。

方式二：自定义setuptools命令 #

如果必须保留setuptools命令形式，可自行实现调用sphinx-build的命令类，示例代码放在setup.py中：

from setuptools import setup
import subprocess

class CustomBuildDoc:
    description = "Build Sphinx documentation"
    user_options = [
        ('source-dir=', 's', 'Source directory for Sphinx docs'),
        ('build-dir=', 'b', 'Build directory for Sphinx docs'),
    ]

    def initialize_options(self):
        self.source_dir = 'docs/source'
        self.build_dir = 'docs/build/html'

    def finalize_options(self):
        pass

    def run(self):
        subprocess.run(
            ['sphinx-build', '-b', 'html', self.source_dir, self.build_dir],
            check=True
        )

setup(
    # 原有项目配置...
    cmdclass={
        'build_sphinx': CustomBuildDoc,
    }
)

之后运行python setup.py build_sphinx即可正常构建文档。

3. Poetry与Sphinx的集成方案 #

用Poetry管理项目时，推荐以下集成方式：

步骤1：安装Sphinx依赖 #

将Sphinx及相关工具添加到开发依赖：

poetry add --dev sphinx sphinx-rtd-theme  # 可按需替换文档主题

步骤2：配置Poetry快捷脚本 #

在pyproject.toml中添加脚本，简化文档构建命令：

[tool.poetry.scripts]
docs-build = "sh:sphinx-build -b html docs/source docs/build/html"

之后直接运行poetry run docs-build即可完成HTML文档构建。

如果需要更灵活的参数控制，也可以绑定Sphinx的官方入口：

[tool.poetry.scripts]
docs-build = "sphinx.cmd.build:build_main"

运行时可手动指定参数：poetry run docs-build -b html docs/source docs/build/html

步骤3：进阶自定义构建（可选） #

如果需要多格式输出、自动生成API文档等复杂逻辑，可编写Python脚本（如docs/build_docs.py）：

import subprocess

def build_docs():
    # 构建HTML文档
    subprocess.run(['sphinx-build', '-b', 'html', 'docs/source', 'docs/build/html'], check=True)
    # 可选：构建PDF文档（需提前安装TeX环境）
    subprocess.run(['sphinx-build', '-b', 'latexpdf', 'docs/source', 'docs/build/pdf'], check=True)

if __name__ == "__main__":
    build_docs()

然后在pyproject.toml中绑定该脚本：

[tool.poetry.scripts]
docs-build = "docs.build_docs:build_docs"

运行poetry run docs-build即可执行自定义构建流程。

内容的提问来源于stack exchange，提问作者João Santos