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 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
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óduloSphinx
make_mode, que fornece a mesma funcionalidade de compilação como padrão Makefile ou Make.bat. Além de todo oSphinx
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
. Selanguage
é'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
ou1
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 osphinx-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 delatex_elements
: i.e.PAPER=a4
configurada para'a4paper'
ePAPER=letter
para'letterpaper'
.Nota
Uso dessa variável de ambiente parece defeituoso em Sphinx 1.5 como
a4
ouletter
para documento LaTeX em lugar dea4paper
ouletterpaper
. 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).
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 executarmake html
(Linux/Mac)set PYTHONWARNINGS=
e executarmake html
(Windows)modificar seu Makefile/make.bat e a variável de ambiente
Ver também¶
sphinx-quickstart(1)