Setuptools集成

Sphinx supports integration with setuptools and distutils through a custom command - BuildDoc.

使用setuptools集成

The Sphinx build can then be triggered from distutils, and some Sphinx options can be set in setup.py or setup.cfg instead of Sphinx’s own configuration file.

例如，来自 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')}},
)

注解

If you set Sphinx options directly in the setup() command, replace hyphens in variable names with underscores. In the example above, source-dir becomes source_dir.

或者在 setup.cfg 中添加此部分:

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

Once configured, call this by calling the relevant command on setup.py:

$ python setup.py build_sphinx

setuptools集成的选项

fresh-env

A boolean that determines whether the saved environment should be discarded on build. Default is false.

这也可以通过将 -E 标志传递给 setup.py 来设置:

$ python setup.py build_sphinx -E
all-files

A boolean that determines whether all files should be built from scratch. Default is false.

这也可以通过将 -a 标志传递给 setup.py 来设置:

$ python setup.py build_sphinx -a
source-dir

The target source directory. This can be relative to the setup.py or setup.cfg file, or it can be absolute. It defaults to ./doc or ./docs if either contains a file named conf.py (checking ./doc first); otherwise it defaults to the current directory.

这也可以通过将 -s 标志传递给 setup.py 来设置:

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

The target build directory. This can be relative to the setup.py or setup.cfg file, or it can be absolute. Default is ./build/sphinx.

config-dir

Location of the configuration directory. This can be relative to the setup.py or setup.cfg file, or it can be absolute. Default is to use 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

A boolean that ensures Sphinx warnings will result in a failed build. Default is false.

这也可以通过将`-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

How to format the current date, used as the replacement for |today|. Default is ''.

1.0 新版功能.

A boolean that ensures index.html will be linked to the master doc. Default is false.

这也可以通过将 -i 标志传递给 setup.py 来设置：

$ python setup.py build_sphinx -i

1.0 新版功能.

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

1.3 新版功能.

nitpicky

Run in nit-picky mode. Currently, this generates warnings for all missing references. See the config value nitpick_ignore for a way to exclude some references as “known missing”.

1.8 新版功能.

pdb

在异常上配置 pdb 的布尔值。默认值为false。

1.5 新版功能.