Construtores

These are the built-in Sphinx builders. More builders can be added by extensions.

The builder’s “name” must be given to the -M or -b command-line options of sphinx-build to select a builder.

The most common builders are:

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.

---

class sphinx.builders.html.StandaloneHTMLBuilder

HTML Esse é o construtor padrão. A saída será no diretório de arquivos HTML, completo com as folhas de estilo e opcionalmente com os fontes reST. Existem alguns valores para configuráveis para personalizar a saída desse construtor, ver o capítulo Opções para saída HTML para detalhes.

name = 'html'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

class sphinx.builders.dirhtml.DirectoryHTMLBuilder

Essa é uma subclasse do construtor HTML. Sua saída é no diretorio de arquivos HTML, onde cada arquivo é nomeado index.html e colocado em um subdiretório igual ao nome da página. Por exemplo, o documento markup/rest.rst não resultará em um arquivo de saída markup/rest.html, mas sim em markup/rest/index.html. Quando gerando links entre páginas, o index.html é omitido, a URL será algo como markup/rest/.

name = 'dirhtml'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Adicionado na versão 0.6.

class sphinx.builders.singlehtml.SingleFileHTMLBuilder

This is an HTML builder that combines the whole project in one output file. (Obviously this only works with smaller projects.) The file is named like the root document. No indices will be generated.

name = 'singlehtml'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Adicionado na versão 1.0.

class sphinxcontrib.htmlhelp.HTMLHelpBuilder

Esse construtor produz a mesma saída do construtor HTML, mas também gerá arquivos de Ajuda HTML, que permitem ao Microsoft Ajuda HTML Workshop compilá-los em um arquivo CHM.

name = 'htmlhelp'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = ['image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

class sphinxcontrib.qthelp.QtHelpBuilder

Esse construtor produz a mesma saída que o construtor HTML e gera também coleção de arquivos Qt help que permite ao gerador Qt compilá-los.

Alterado na versão 2.0: Moved to sphinxcontrib.qthelp from sphinx.builders package.

name = 'qthelp'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

class sphinxcontrib.applehelp.AppleHelpBuilder

Esse construtor produz um Livro Help Apple baseado na mesma saída do construtor HTML.

Se o diretório fonte contiver alguma pasta .lproj, então o idioma correspondente será combinado com a saída gerada. Essas pastas serão ignoradas por todos os outros tipos de documentação.

Para gerar um livro de ajuda válido, esse construtor requer o uso da ferramenta de linha de comando hiutil, o qual só está disponível no Mac OS X 10.6 ou versão posterior. O passo da indexação pode ser desabilitado com a configuração True applehelp_disable_external_tools e nesse caso a saída não será válida até o término do hiutil.

name = 'applehelp'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = ['image/png', 'image/gif', 'image/jpeg', 'image/tiff', 'image/jp2', 'image/svg+xml']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Adicionado na versão 1.3.

Alterado na versão 2.0: Moved to sphinxcontrib.applehelp from sphinx.builders package.

class sphinxcontrib.devhelp.DevhelpBuilder

Esse construtor produz a mesma saída que o construtor HTML e também gera arquivos de suporte GNOME Devhelp o que permite que o leitor GNOME Devhelp possa visualizá-los.

name = 'devhelp'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = ['image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Alterado na versão 2.0: Moved to sphinxcontrib.devhelp from sphinx.builders package.

class sphinx.builders.epub3.Epub3Builder

This builder produces the same output as the standalone HTML builder, but also generates an epub file for ebook readers. See Informações de epub for details about it. For definition of the epub format, have a look at https://idpf.org/epub or https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3 files.

name = 'epub'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Adicionado na versão 1.4.

Alterado na versão 1.5: Since Sphinx 1.5, the epub3 builder is used as the default epub builder.

class sphinx.builders.latex.LaTeXBuilder

This builder produces LaTeX source files in the output directory. The actual PDF builds happen inside this output directory and need to be triggered in a second step. This can be done via make all-pdf there. To combine the two steps into only one, use sphinx-build -M (i.e. -M latexpdf not -b latexpdf) or make latexpdf at the project root.

See latex_documents and the chapter Opções para saída LaTeX for available options.

PDF builds need a sufficiently complete LaTeX installation. The testing is currently (since 5.3.0) done on Ubuntu 22.04LTS, whose LaTeX distribution matches upstream TeXLive 2021 as of 2022/02/04, but PDF builds can be successfully done on much older LaTeX installations.

At any rate, on Ubuntu for example, following packages must all be present:

• texlive-latex-recommended

• texlive-fonts-recommended

• tex-gyre (if latex_engine left to default)

• texlive-latex-extra

• latexmk

Alterado na versão 4.0.0: TeX Gyre fonts now required for 'pdflatex' engine (default).

Additional packages are needed in some circumstances:

• texlive-lang-cyrillic for Cyrillic (and also then cm-super if using the default fonts),

• texlive-lang-greek for Greek (and also then cm-super if using the default fonts),

• texlive-xetex if latex_engine is 'xelatex',

• texlive-luatex if latex_engine is 'lualatex',

• fonts-freefont-otf if latex_engine is either 'xelatex' or 'lualatex'.

Nota

Since 1.6, make latexpdf uses on GNU/Linux and macOS latexmk, as it makes sure the needed number of runs is automatically executed. On Windows the PDF builds execute a fix number of LaTeX runs (three, then makeindex, then two more).

Podem ser passadas ao latexmk opções via LATEXMKOPTS variável Makefile. Por exemplo:

make latexpdf LATEXMKOPTS="-silent"

reduz saída na console ao mínimo.

Also, if latexmk is at version 4.52b or higher (January 2017) LATEXMKOPTS="-xelatex" speeds up PDF builds via XeLateX in case of numerous graphics inclusions.

To pass options directly to the (pdf|xe|lua)latex binary, use variable LATEXOPTS, for example:

make latexpdf LATEXOPTS="--halt-on-error"

name = 'latex'

The builder’s name, for the -b command line option.

format = 'latex'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = ['application/pdf', 'image/png', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Observe que um construtor do dicrect PDF está sendo fornecido por rinohtype. O nome do construtor é rinoh. Consulte o manual do rinohtype para detalhes.

class sphinx.builders.text.TextBuilder

Esse construtor produz um arquivo texto para cada arquivo reST – e é exatamente o mesmo que a fonte reST, mas sem as marcações que são suprimidas para melhor legibilidade.

name = 'text'

The builder’s name, for the -b command line option.

format = 'text'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Adicionado na versão 0.4.

class sphinx.builders.manpage.ManualPageBuilder

Esse construtor produz páginas de manual no formato groff. Especificar quais documentos serão incluídos em quais páginas de manual através do valor de configuração man_pages.

name = 'man'

The builder’s name, for the -b command line option.

format = 'man'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Adicionado na versão 1.0.

class sphinx.builders.texinfo.TexinfoBuilder

Esse construtorproduz arquivos Texinfo que podem ser processados em arquivos Info através do makeinfo. Especificar quais documentos serão incluídosem quais arquivos Texinfo através do valor de configuração texinfo_documents.

Formato Info é a base da ajuda on-line usado por GNU Emacs e por programas baseados em termina info. Veja Informações de Texinfo para mais detalhes. O formato Texinfo é o sistema de documentação usado pelo projeto GNU. Mais informações sobre o Texinfo podem ser encontradas em https://www.gnu.org/software/texinfo/.

name = 'texinfo'

The builder’s name, for the -b command line option.

format = 'texinfo'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = ['image/png', 'image/jpeg', 'image/gif']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Adicionado na versão 1.1.

class sphinxcontrib.serializinghtml.SerializingHTMLBuilder

This builder uses a module that implements the Python serialization API (pickle, simplejson, phpserialize, and others) to dump the generated HTML documentation. The pickle builder is a subclass of it.

O formato de uma subclasse concreta desse construtor de serialização para PHP serialization aparenta:

import phpserialize

class PHPSerializedBuilder(SerializingHTMLBuilder):
    name = 'phpserialized'
    implementation = phpserialize
    out_suffix = '.file.phpdump'
    globalcontext_filename = 'globalcontext.phpdump'
    searchindex_filename = 'searchindex.phpdump'

implementation

A module that implements dump(), load(), dumps() and loads() functions that conform to the functions with the same names from the pickle module. Known modules implementing this interface are simplejson, phpserialize, plistlib, and others.

out_suffix

O sufixo para todos arquivos padrão.

globalcontext_filename

O nome do arquivo que contém a “contexto global”. Essa é uma configuração dicionário com alguns valores como nome do projeto.

searchindex_filename

O nome do arquivo para índice de busca que o Sphinx irá criar.

Ver Detalhes Construtor de Serialização para detalhes sobre formato de saída.

Adicionado na versão 0.5.

class sphinxcontrib.serializinghtml.PickleHTMLBuilder

Esse construtor produz um diretório com arquivos com fragmentos de HTML e informações TOC tabela de conteúdo, para uso pela aplicação web (ou ferramenta personalizada pós processamento) que não utiliza modelos HTML padrão.

Ver Detalhes Construtor de Serialização para detalhes sobre formato de saída.

name = 'pickle'

The builder’s name, for the -b command line option.

O antigo nome web também continua funcionando.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

O sufixo do arquivo é .fpickle. O contexto global é chamado globalcontext.pickle, o índice pesquisa searchindex.pickle.

class sphinxcontrib.serializinghtml.JSONHTMLBuilder

Esse construtor produz um diretório com arquivos JSON contendo maioria das informações HTML e TOC tabela de conteúdo, para uso da aplicação web (ou ferramenta de pós processamento) que não utilize modelos HTML padrão.

Ver Detalhes Construtor de Serialização para detalhes sobre formato de saída.

name = 'json'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

O sufixo do arquivo é .fjson. O contexto global é chamado globalcontext.json``e o índice de busca ``searchindex.json.

Adicionado na versão 0.5.

class sphinx.builders.gettext.MessageCatalogBuilder

Esse construtor produz catálogos de mensagem estilo gettext. Cada arquivo de topo de nível ou subdiretório gera um simples catálogo padrão .pot.

Para referências adicionais ver a documentação Internacionalização

name = 'gettext'

The builder’s name, for the -b command line option.

format = ''

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Adicionado na versão 1.1.

class sphinx.builders.changes.ChangesBuilder

This builder produces an HTML overview of all versionadded, versionchanged, deprecated and versionremoved directives for the current version. This is useful to generate a changelog file, for example.

name = 'changes'

The builder’s name, for the -b command line option.

format = ''

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

class sphinx.builders.dummy.DummyBuilder

Esse construtor não produz saída. A entra é passada e verificada só para consistência. Isso é útil para diversos propósitos.

name = 'dummy'

The builder’s name, for the -b command line option.

supported_image_types: list[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Adicionado na versão 1.4.

class sphinx.builders.linkcheck.CheckExternalLinksBuilder

Esses construtores buscam em todos os documentos para ligações externas, tenta abrir esses links com requests, e grava uma visão com os inconsistentes e redireciona para a saída padrão e para output.txt no diretório de saída.

name = 'linkcheck'

The builder’s name, for the -b command line option.

format = ''

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Alterado na versão 1.5: Since Sphinx 1.5, the linkcheck builder uses the requests module.

Alterado na versão 3.4: The linkcheck builder retries links when servers apply rate limits.

class sphinx.builders.xml.XMLBuilder

Esse construtor produz arquivos XML nativos Docutils. A saída pode ser transformada com ferramentas XML padrão como processadores XSLT em formulários prontos arbitrários.

name = 'xml'

The builder’s name, for the -b command line option.

format = 'xml'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Adicionado na versão 1.2.

class sphinx.builders.xml.PseudoXMLBuilder

Esse construtor é usado para depuração do Sphinx/Docutils na linha “Leitor para Transformador para Escritor”. Produz arquivos de counteúdo formatado “pseudo-XML”, aninhados por identação (sem marcas finais). Atributos externos para todos elementos são criados bem como atributos internos para qualquer pendência de elemento, também é dada.

name = 'pseudoxml'

The builder’s name, for the -b command line option.

format = 'pseudoxml'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: list[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Adicionado na versão 1.2.

Extensões embutidas do Sphinx que oferecem mais construtores são:

• doctest

• coverage

Detalhes Construtor de Serialização

Todos os construtores de serialização produzem saída em um arquivo para cada arquivo fonte e alguns arquivos especiais. Também são copiados os arquivos fonte reST do diretório _sources para o diretório de saída.

A PickleHTMLBuilder é uma subclasse implícita que implementa o interface de serialização.

Os arquivos dos fontes tem extensão out_suffix, e são arranjados em diretórios como estão os arquivos fonte. São desconstruídos para um dicionário (ou estrutura similar a um dicionário) com essas chaves:

body

O “corpo” HTML (que é o HTML renderizado do arquivo fonte), como renderizado pelo tradutor HTML.

title

O título do documento, como HTML (pode conter marcas).

toc

Tabela de conteúdo do arquivo ou sumário, renderizado como HTML <ul>.

display_toc

Um booleano que é True se o toc contém mais que uma entrada.

current_page_name

Nome do documento corrente do arquivo corrente.

parents, prev and next

Informação sobre os capítulos relacionados com a árvore do TOC. Cada relação é um dicionario com as chaves link (HREF da relação) e title (título do documento relacionado, como HTML). parents é a lista de relações, enquanto prev e next são relações simples.

sourcename

O nome do arquivo fonte sob _sources.

Arquivos especiais localizados na raiz do diretório. São eles:

SerializingHTMLBuilder.globalcontext_filename

Um dicionário montado com as seguintes chaves:

project, copyright, release, version

Os mesmos valores informados no arquivo de configuração.

style

html_style.

last_updated

Data da última construção.

builder

Nome do construtor usado, no caso de montagens será sempre 'pickle'.

titles

Um dicionário com todos os títulos de documentos, como strings HTML.

SerializingHTMLBuilder.searchindex_filename

Um índice que pode ser usado para busca nos documentos. É uma lista com estas entradas:

• Lista de nomes de documentos indexados.

• Uma lista de títulos de documentos, como strings HTML, na mesma ordem da primeira lista.

• Dicionário mapeando palavras raízes (processadas por tratamento idioma Inglês) para uma lista de inteiros, os quais possuem índices na primeira lista.

environment.pickle

O ambiente do construtor. Sempre é um arquivo pickle, independentemente do construtor e uma cópia do ambiente usado quando o construtor foi iniciado.

Por fazer

Membros comuns do documento.

Diferentemente de outros arquivos pickle, esse arquivo requer que o pacote sphinx esteja disponível no processo.