sphinx-build

Sinopse

sphinx-build [opções] <diretori-fonte> <diretori-saida> [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 pode criar documentação em diversos formatos. Um formato é selecionado especificando o nome do construtor; o padrão é HTML. Esses construtores também pode executar outras tarefas relacionadas ao processamento da documentação. Para uma lista de construtores disponíveis, consulte sphinx-build -b.

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

-b buildername

A opção mais importante: ela seleciona o construtor. Os mais comuns são:

html

Constrói páginas HTML. Esse é o construtor padrão.

dirhtml

Constrói páginas HTML, mas em um simples diretório por documento. Torna simples URL (não há .html) quando servido de um webserver.

singlehtml

Constrói um único HTML com todo o conteúdo.

htmlhelp, qthelp, devhelp, epub

Constrói arquivos HTML com informação adicional para construção de uma coleção em um ou mais formatos.

applehelp

Constrói um Apple Help Book. Requer hiutil e o codesign, os quais não são Open Source e atualmente estão disponíveis somente em Mac OS X 10.6 ou superior.

latex

Constrói fontes LaTeX que serão compilados em um documento PDF usando o pdflatex.

man

Constrói páginas do manual no formato groff para sistemas UNIX.

texinfo

Constrói arquivos Texinfo que podem ser processados em arquivos Info usando makeinfo.

text

Constrói arquivos texto puro.

gettext

Constrói catalogo de mensagens tipo gettext (arquivos .pot).

doctest

Executa todos doctests na documentação, se a extensão doctest estiver habilitada

linkcheck

Verifica a integridade dos links externos.

xml

Constrói arquivos XML nativos Docutils.

pseudoxml

Constrói versão compacta dos arquivos “pseudo-XML” exibindo a estrutura interna intermediária do documento.

Consulte Builders para obter uma lista de todos os construtores fornecidos com o Sphinx. As extensões podem adicionar seus próprios construtores.

-M buildername

Alternativa para -b. Usa o módulo Sphinx make_mode, que fornece a mesma funcionalidade de compilação como padrão Makefile ou Make.bat. Além de todo o Sphinx Builders, os seguintes pipelines de construção estão disponíveis:

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.

Importante

Sphinx só reconhece a opção -M se informada em primeiro lugar.

Novo na versão 1.2.1.

-a

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).

-E

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.

-t tag

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

Novo na versão 0.6.

-d 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).

-j 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.

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

Alterado na versão 1.7: Suporta argumento auto.

-c 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.

Novo na versão 0.3.

-C

Não usar arquivo de configuração; obter opções via opção -D .

Novo na versão 0.5.

-D 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.

-A name=value

Tornar o name assinalado para value nos modelos HTML.

Novo na versão 0.5.

-n

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

-N

Não emitir saída colorida.

-v

Incrementar verborragia (loglevel). Essa opção pode ser dada até três vezes mais para maior detalhe de log na saída. Isso implica -T.

Novo na versão 1.2.

-q

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

-Q

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.

-w file

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

-W

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.

--keep-going

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

Novo na versão 1.8.

-T

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.

Novo na versão 1.2.

-P

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

-h, --help, --version

Exibir sumário uso ou versão Sphinx.

Novo 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.

Novo 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.

Novo 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)