Integração Setuptools

Sphinx suporta integração com setuptools e distutils através de comando personalizado - BuildDoc.

Obsoleto desde a versão 5.0: Este recurso será removido na v7.0.

Usando integração setuptools

A construção do Sphinx pode então ser disparada a partir de distutils, e algumas opções do Sphinx podem ser configuradas em setup.py ou setup.cfg em vez do próprio arquivo de configuração do Sphinx.

Por exemplo, de 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')}},
)

Nota

Se você definir as opções do Sphinx diretamente no comando setup(), substitua os hifens em nomes de variáveis por sublinhados. No exemplo acima, source-dir se torna source_dir.

Ou adicione esta seção em setup.cfg:

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

Uma vez configurado, chame isso chamando o comando relevante em setup.py:

$ python setup.py build_sphinx

Opções para integração setuptools

fresh-env

Um booleano que determina se o ambiente salvo deve ser descartado na compilação. O padrão é False.

Isso também pode ser definido passando a flag -E para setup.py:

$ python setup.py build_sphinx -E
all-files

Um booleano que determina se todos os arquivos devem ser construídos do zero. O padrão é False.

Isso também pode ser definido passando a flag -a para setup.py:

$ python setup.py build_sphinx -a
source-dir

O diretório de origem do destino. Isso pode ser relativo ao arquivo setup.py ou setup.cfg, ou pode ser absoluto. O padrão é ./doc ou ./docs se ambos contiverem um arquivo chamado conf.py (verificando ./doc primeiro); caso contrário, o padrão será o diretório atual.

Isso também pode ser definido passando a flag -s para setup.py:

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

O diretório de construção de destino. Isso pode ser relativo ao arquivo setup.py ou setup.cfg, ou pode ser absoluto. O padrão é ./build/sphinx.

config-dir

Localização do diretório de configuração. Isso pode ser relativo ao arquivo setup.py ou setup.cfg, ou pode ser absoluto. O padrão é usar source-dir.

Isso também pode ser definido passando a flag -c para setup.py:

$ python setup.py build_sphinx -c $CONFIG_DIR

Novo na versão 1.0.

builder

O construtor ou lista de construtores a serem usados. O padrão é html.

Isso também pode ser definido passando a flag -b para o setup.py:

$ python setup.py build_sphinx -b $BUILDER

Alterado na versão 1.6: Agora, isso pode ser uma lista separada por vírgula ou espaço de construtores

warning-is-error

Um booleano que garanta avisos do Sphinx resultará em uma falha na construção. O padrão é False.

Isso também pode ser definido passando a flag -W para setup.py:

$ python setup.py build_sphinx -W

Novo na versão 1.5.

project

Nome do documento do Projeto. padrão é ''.

Novo na versão 1.0.

version

A versão curta do X.Y. O padrão é ''.

Novo na versão 1.0.

release

A versão completa, incluindo tags alfa/beta/rc. O padrão é ''.

Novo na versão 1.0.

today

Como formatar a data atual, usada como substituta para |today|. O padrão é ''.

Novo na versão 1.0.

Um booleano que garante que index.html será vinculado ao documento raiz. O padrão é falso.

Isso também pode ser definido passando a flag -i para setup.py:

$ python setup.py build_sphinx -i

Novo na versão 1.0.

String de Direito Autoral. Padrão é ''.

Novo na versão 1.3.

nitpicky

Executar no modo nit-picky. Atualmente, isso gera avisos para todas as referências inexistentes. Ver valor config nitpick_ignore para não exibir referências conhecidas como “inexistentes conhecidos”.

Novo na versão 1.8.

pdb

Um booleano para configurar pd na exceção. O padrão é False.

Novo na versão 1.5.