sphinx-build

Sinopse

sphinx-build [opções] <diretório-fonte> <diretório-saída> [arquivos-nomes …]

Descrição

sphinx-build gera documentação dos arquivos que estão em <sourcedir> e monta documento final em <outputdir>.

sphinx-build busca no <diretóriofonte>/conf.py por um arquivo de configurações. sphinx-quickstart(1) pode ser usado para gerar modelos de arquivos, inclusive o arquivo conf.py.

sphinx-build can create documentation in different formats. A format is selected by specifying the builder name on the command line; it defaults to HTML. Builders can also perform other tasks related to documentation processing. For a list of available builders, refer to Builders.

Por padrão tudo que estiver desatualizado é reconstruído. Saída de apenas alguns arquivos pode ser construída através da especificação individual desses arquivos.

Opções

-M buildername

Select a builder, using the make-mode. See Builders for a list of all of Sphinx’s built-in builders. Extensions can add their own builders.

Importante

Sphinx only recognizes the -M option if it is used first, along with the source and output directories, before any other options are passed. For example:

sphinx-build -M html ./source ./build -W --keep-going

The make-mode provides the same build functionality as a default Makefile or Make.bat, and provides the following additional build pipelines:

latexpdf

Constrói arquivos LaTeX e executa cada um deles através do pdflatex ou através da configuração latex_engine. Se language é 'ja', irá usar automaticamente pipeline latex platex/dvipdfmx para PDF.

info

Constrói arquivos Texinfo e executa cada um através de makeinfo.

Nota

The default output directory locations when using make-mode differ from the defaults when using -b.

• doctrees are saved to <outputdir>/doctrees

• output files are saved to <outputdir>/<builder name>

Adicionado na versão 1.2.1.

-b buildername, --builder buildername

Selects a builder.

See Builders for a list of all of Sphinx’s built-in builders. Extensions can add their own builders.

Alterado na versão 7.3: Add --builder long option.

-a, --write-all

Se informado, sempre sobrepõe a gravação de todos arquivos. O padrão é sobrepor somente arquivos de saída para novos e modificados. (isso não se aplica a todos construtores).

Nota

This option does not re-read source files. To read and re-process every file, use --fresh-env instead.

Alterado na versão 7.3: Add --write-all long option.

-E, --fresh-env

Não usar environment salvo (a estrutura faz cache das ref. cruzadas), mas reconstruir completamente. O padrão é só ler e fazer parse dos arquivos fonte que forem novos ou foram atualizados desde a última execução.

Alterado na versão 7.3: Add --fresh-env long option.

-t tag, --tag tag

Definir o rótulo tag. Isso é relevante para diretivas only que incluem somente seu conteúdo se esse rótulo é definido.

Adicionado na versão 0.6.

Alterado na versão 7.3: Add --tag long option.

-d path, --doctree-dir path

Sphinx leu e fez parse de todos fontes antes de gravar saída nos arquivos, esses arquivos fontes são mantidos em cache como “doctree pickles”. Normalmente, esses arquivos são gravados em um diretório chamado .doctrees sob o diretório onde está sendo feito o build; com essa opção pode ser selecionado um diretório cache diferente (doctrees podem ser compartilhados entre vários construtores).

Alterado na versão 7.3: Add --doctree-dir long option.

-j N, --jobs N

Distribuir a montagem através de N processos em paralelo, para permitir o processo de construção em máquinas com múltiplos processadores ser mais efetivo. Note que nem todas as partes nem todos os construtores do Sphinx podem ser executados em paralelo. Se argumento auto é fornecido, Então o Sphinx usa o número de CPUs como N.

Adicionado na versão 1.2: Opção considerada experimental.

Alterado na versão 1.7: Suporta argumento auto.

Alterado na versão 6.2: Add --jobs long option.

-c path, --config-dir path

Não procure pelo conf.py no diretório fonte, mas use o diretório informado na configuração. Note que outros arquivos e caminhos obtidos pelos valores da configuração são esperados como relativos ao diretório da configuração, portanto também devem estar presentes nessa localização.

Adicionado na versão 0.3.

Alterado na versão 7.3: Add --config-dir long option.

-C, --isolated

Don’t look for a configuration file; only take options via the --define option.

Adicionado na versão 0.5.

Alterado na versão 7.3: Add --isolated long option.

-D setting=value, --define setting=value

Sobrepôr valor da configuração definido no arquivo conf.py. O valor deve ser número, string, lista ou dicionário.

Para listas, pode separar os elementos por vírgulas como esse: -D html_tema_caminho=caminho1,caminho2.

Para valores dicionário, forneça o nome opção e a chave como -D latex_elements.docclass=scrartcl.

Para valores booleanos, use 0 ou 1 como valor.

Alterado na versão 0.6: O valor pode ser um valor de dicionário.

Alterado na versão 1.3: O valor pode ser um valor de lista.

Alterado na versão 7.3: Add --define long option.

-A name=value, --html-define name=value

Tornar o name assinalado para value nos modelos HTML.

Adicionado na versão 0.5.

Alterado na versão 7.3: Add --html-define long option.

-n, --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”.

Alterado na versão 7.3: Add --nitpicky long option.

-N, --no-color

Não emitir saída colorida.

Alterado na versão 1.6: Add --no-color long option.

--color

Emit colored output. Auto-detected by default.

Adicionado na versão 1.6.

-v, --verbose

Increase verbosity (log-level). This option can be given up to three times to get more debug logging output. It implies -T.

Adicionado na versão 1.2.

Alterado na versão 7.3: Add --verbose long option.

-q, --quiet

Não emitir saída nenhuma na saída padrão, só gravar avisos de erros na saída padrão de erros.

Alterado na versão 7.3: Add --quiet long option.

-Q, --silent

Não emitir nenhuma saída na saída padrão, também suprimir avisos. Só erros serão exibidos na saída padrão de erros.

Alterado na versão 7.3: Add --silent long option.

-w file, --warning-file file

Write warnings (and errors) to the given file, in addition to standard error.

Alterado na versão 7.3: ANSI control sequences are stripped when writing to file.

Alterado na versão 7.3: Add --warning-file long option.

-W, --fail-on-warning

Tornar avisos em erros. Isso significa que a construção irá ser interrompida ao primeiro aviso e sphinx-build irá terminar e sair com situação (status) 1.

Alterado na versão 7.3: Add --fail-on-warning long option.

--keep-going

Com a opção -W, continua processando ao receber avisos até o final da construção, e o sphinx-build sairá com o status de saída 1.

Adicionado na versão 1.8.

-T, --show-traceback

Exibir rastreabilidade completa quando uma exceção não tratada ocorrer. Caso contrário, só um resumo será exibido e a informação do rastreamento será salva em arquivo para análise posterior.

Adicionado na versão 1.2.

Alterado na versão 7.3: Add --show-traceback long option.

-P, --pdb

(Útil só para depuração). Executar debug Python, pdb, se excessão não tratada ocorrer enquanto constrói.

Alterado na versão 7.3: Add --pdb long option.

-h, --help, --version

Exibir sumário uso ou versão Sphinx.

Adicionado na versão 1.2.

Também pode ser informado um ou mais nomes de arquivo na linha de comando após o diretório fonte e o de montagem. Sphinx irá tentar construir esses arquivos de saída (bem como suas dependências).

variáveis de ambiente

O sphinx-build usa as seguintes variáveis de ambiente:

MAKE

O caminho para o comando make. O nome do comando também é permitido. sphinx-build usa isso para chamar processos dependentes para montador no modo make.

Opções de Make

Os arquivos Makefile e make.bat criados pelo sphinx-quickstart normalmente executar sphinx-build só com a opção -b e -d. Contudo suportam as seguintes variáveis para personalizar o comportamento:

PAPER

Isso configura 'papersize' chave de latex_elements: i.e. PAPER=a4 configurada para 'a4paper' e PAPER=letter para 'letterpaper'.

Nota

Uso dessa variável de ambiente parece defeituoso em Sphinx 1.5 como a4 ou letter para documento LaTeX em lugar de a4paper ou letterpaper. Corrigido em 1.7.7.

SPHINXBUILD

O comando para usar em vez de sphinx-build.

BUILDDIR

O diretório onde será construído em vez de um escolhido pelo sphinx-quickstart.

SPHINXOPTS

Opções adicionais para sphinx-build. Essas opções também podem ser definidas por meio da variável de atalho O (‘o’ maiúsculo).

NO_COLOR

Quando definido (independentemente do valor), sphinx-build não usará cores na saída do terminal. NO_COLOR tem precedência sobre FORCE_COLOR. Veja no-color.org para outras bibliotecas que oferecem suporte a este padrão da comunidade.

Adicionado na versão 4.5.0.

FORCE_COLOR

Quando definido (independentemente do valor), sphinx-build usará cores na saída do terminal. NO_COLOR tem precedência sobre FORCE_COLOR.

Adicionado na versão 4.5.0.

Avisos de Obsoleto

Se qualquer aviso como RemovedInSphinxXXXWarning for exibido quando for construir o documento, e algumas extensões Sphinx estiverem referenciando funcionalidades tornadas obsoletas. Nesse caso favor entrar em contato com o autor da extensão.

Para desabilitar avisos de obsoleto, favor ver variável de ambiente PYTHONWARNINGS=. Por exemplo:

• PYTHONWARNINGS= make html (Linux/Mac)

• export PYTHONWARNINGS= e executar make html (Linux/Mac)

• set PYTHONWARNINGS= e executar make html (Windows)

• modificar seu Makefile/make.bat e a variável de ambiente

Ver também

sphinx-quickstart(1)