设置工具集成

sphinx支持通过自定义命令与setuptools和distuils集成- BuildDoc .

自 5.0 版本弃用: 该功能将在V7.0中删除。

使用设置工具集成

然后可以从distuils触发sphinx构建，并且可以在中设置一些sphinx选项 setup.py 或 setup.cfg 而不是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')}},
)

备注

如果直接在 setup() 命令，用下划线替换变量名中的连字符。在上面的例子中， source-dir 变成 source_dir .

或将此节添加到 setup.cfg ：：

[build_sphinx]
project = 'My project'
version = 1.2
release = 1.2.0
source-dir = 'doc'

配置完成后，通过调用 setup.py ：：

$ python setup.py build_sphinx

设置工具集成选项

fresh-env

确定在生成时是否应丢弃保存的环境的布尔值。默认值为假。

也可以通过传递 -E 旗到 setup.py ：

$ python setup.py build_sphinx -E
all-files

一个布尔值，用于确定是否应从头开始生成所有文件。默认值为假。

也可以通过传递 -a 旗到 setup.py ：

$ python setup.py build_sphinx -a
source-dir

目标源目录。这可以是相对于 setup.py 或 setup.cfg 文件，或者它可以是绝对的。它默认为 ./doc 或 ./docs 如果其中一个包含名为 conf.py （检查） ./doc 首先）；否则它默认为当前目录。

也可以通过传递 -s 旗到 setup.py ：

$ python setup.py build_sphinx -s $SOURCE_DIR
build-dir

目标生成目录。这可以是相对于 setup.py 或 setup.cfg 文件，或者它可以是绝对的。默认是 ./build/sphinx .

config-dir

配置目录的位置。这可以是相对于 setup.py 或 setup.cfg 文件，或者它可以是绝对的。默认为使用 source-dir .

也可以通过传递 -c 旗到 setup.py ：

$ python setup.py build_sphinx -c $CONFIG_DIR

在 1.0 版本加入.

builder

要使用的生成器或生成器列表。默认是 html .

也可以通过传递 -b 旗到 setup.py ：

$ python setup.py build_sphinx -b $BUILDER

在 1.6 版本发生变更: 这现在可以是一个逗号或空格分隔的生成器列表

warning-is-error

确保Sphinx警告的布尔值将导致生成失败。默认值为假。

也可以通过传递 -W 旗到 setup.py ：

$ python setup.py build_sphinx -W

在 1.5 版本加入.

project

记录的项目名称。默认是 '' .

在 1.0 版本加入.

version

简短的X.Y版本。默认是 '' .

在 1.0 版本加入.

release

完整版本，包括alpha/beta/rc标签。默认是 '' .

在 1.0 版本加入.

today

如何设置当前日期的格式，用作 |today| . 默认是 '' .

在 1.0 版本加入.

确保index.html链接到根文档的布尔值。默认值为FALSE。

也可以通过传递 -i 旗到 setup.py ：

$ python setup.py build_sphinx -i

在 1.0 版本加入.

版权字符串。默认是 '' .

在 1.3 版本加入.

nitpicky

在挑剔的模式下运行。当前，这会为所有缺少的引用生成警告。查看配置值 nitpick_ignore 为了排除一些“已知缺失”的引用。

在 1.8 版本加入.

pdb

要配置的布尔值 pdb 例外情况。默认值为假。

在 1.5 版本加入.