Construtores

Esses são os construtores embutidos do Sphinx. Mais construtores podem ser adicionados através das extensões.

O “nome” do construtor deve ser passado para as opções de linha de comando -M ou -b do sphinx-build para selecionar o construtor.

Os construtores mais comuns são:

html

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

dirhtml

Constrói páginas HTML, mas em um único diretório por documento. Cria URLs mais bonitas (sem .html) quando servido de um servidor web.

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 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 man 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 de árvores de documentos, doctrees.


class sphinx.builders.html.StandaloneHTMLBuilder[código fonte]

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'

O nome do construtor, para a opção de linha de comando -b.

format = 'html'

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

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

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

class sphinx.builders.dirhtml.DirectoryHTMLBuilder[código fonte]

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'

O nome do construtor, para a opção de linha de comando -b.

format = 'html'

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

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

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

Adicionado na versão 0.6.

class sphinx.builders.singlehtml.SingleFileHTMLBuilder[código fonte]

Esse é um construtor HTML que combina todo o projeto em um único arquivo de saída, (obviamente isso só funciona em pequenos projetos). O arquivo será nomeado como documento raiz. Nenhum índice será gerado.

name = 'singlehtml'

O nome do construtor, para a opção de linha de comando -b.

format = 'html'

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

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

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

Adicionado na versão 1.0.

class sphinxcontrib.htmlhelp.HTMLHelpBuilder[código fonte]

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'

O nome do construtor, para a opção de linha de comando -b.

format = 'html'

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

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

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

class sphinxcontrib.qthelp.QtHelpBuilder[código fonte]

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: Movido para sphinxcontrib.qthelp do pacote sphinx.builders.

name = 'qthelp'

O nome do construtor, para a opção de linha de comando -b.

format = 'html'

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

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

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

class sphinxcontrib.applehelp.AppleHelpBuilder[código fonte]

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 applehelp_disable_external_tools com True, caso em que a saída não será válida até o término do hiutil ter sido executado em todas as pastas .lproj dentro do pacote.

name = 'applehelp'

O nome do construtor, para a opção de linha de comando -b.

format = 'html'

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

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

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

Adicionado na versão 1.3.

Alterado na versão 2.0: Movido para sphinxcontrib.applehelp do pacote sphinx.builders.

class sphinxcontrib.devhelp.DevhelpBuilder[código fonte]

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'

O nome do construtor, para a opção de linha de comando -b.

format = 'html'

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

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

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

Alterado na versão 2.0: Movido para sphinxcontrib.devhelp do pacote sphinx.builders.

class sphinx.builders.epub3.Epub3Builder[código fonte]

Esse construtor produz a mesma saída do construtor HTML e também gera arquivos epub para leitores de ebook readers. Veja Informações de epub para detalhes sobre isso. Para definições do formato epub, veja https://idpf.org/epub ou https://en.wikipedia.org/wiki/EPUB. O construtor cria arquivos EPUB 3.

name = 'epub'

O nome do construtor, para a opção de linha de comando -b.

format = 'html'

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

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

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

Adicionado na versão 1.4.

Alterado na versão 1.5: Desde Sphinx 1.5, o construtor epub3 é usado como o construtor padrão de epub.

class sphinx.builders.latex.LaTeXBuilder[código fonte]

Este construtor produz arquivos fonte LaTeX no diretório de saída. As construções reais do PDF acontecem dentro deste diretório de saída e precisam ser acionadas em uma segunda etapa. Isso pode ser feito via make all-pdf. Para combinar as duas etapas em apenas uma, use sphinx-build -M (ou seja, -M latexpdf e não -b latexpdf) ou make latexpdf na raiz do projeto.

Veja latex_documents e o capítulo Opções para saída LaTeX para opções disponíveis.

As construções de PDF precisam de uma instalação LaTeX suficientemente completa. O teste é atualmente (desde 5.3.0) feito no Ubuntu 22.04LTS, cuja distribuição LaTeX corresponde ao TeXLive 2021 upstream em 04/02/2022, mas construções de PDF podem ser feitas com sucesso em instalações LaTeX muito mais antigas.

De qualquer forma, no Ubuntu, por exemplo, os seguintes pacotes devem estar presentes:

  • texlive-latex-recommended

  • texlive-fonts-recommended

  • tex-gyre (se latex_engine deixado como padrão)

  • texlive-latex-extra

  • latexmk

Alterado na versão 4.0.0: Fontes TeX Gyre agora são necessárias para o mecanismo 'pdflatex' (padrão).

Pacotes adicionais são necessários em algumas circunstâncias:

  • texlive-lang-cyrillic para cirílico (e também cm-super se estiver usando as fontes padrão),

  • texlive-lang-greek para grego (e também cm-super se estiver usando as fontes padrão),

  • texlive-xetex se latex_engine é 'xelatex',

  • texlive-luatex se latex_engine é 'lualatex',

  • fonts-freefont-otf se latex_engine é ou 'xelatex' ou 'lualatex'.

Nota

Desde a versão 1.6, make latexpdf usa no GNU/Linux e macOS latexmk, pois garante que o número necessário de execuções seja executado automaticamente. No Windows, as construções de PDF executam um número fixo de execuções de LaTeX (três, depois makeindex e mais duas).

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.

Além disso, se latexmk estiver na versão 4.52b ou posterior (Janeiro de 2017), LATEXMKOPTS="-xelatex" aumenta a velocidade da construção de PDF via XeLateX em caso de inclusões diversos gráficos.

Para passar opções diretamente ao binário (pdf|xe|lua)latex, use a variável LATEXOPTS. por exemplo:

make latexpdf LATEXOPTS="--halt-on-error"
name = 'latex'

O nome do construtor, para a opção de linha de comando -b.

format = 'latex'

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

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

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

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[código fonte]

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'

O nome do construtor, para a opção de linha de comando -b.

format = 'text'

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

supported_image_types: list[str] = []

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

Adicionado na versão 0.4.

class sphinx.builders.manpage.ManualPageBuilder[código fonte]

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'

O nome do construtor, para a opção de linha de comando -b.

format = 'man'

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

supported_image_types: list[str] = []

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

Adicionado na versão 1.0.

class sphinx.builders.texinfo.TexinfoBuilder[código fonte]

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'

O nome do construtor, para a opção de linha de comando -b.

format = 'texinfo'

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

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

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

Adicionado na versão 1.1.

class sphinxcontrib.serializinghtml.SerializingHTMLBuilder[código fonte]

Esse construtor usa um módulo que implementa API de serialização Python (pickle, simplejson, phpserialize e outros) para dump da documentação HTML gerada. O construtor pickle é uma subclasse desse construtor.

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

O módulo que implementa funções dump(), load(), dumps() e loads() em acordo com funções com o mesmo nome do módulo usado. Módulos conhecidos que implementam essa interface são simplejson, phpserialize, plistlib e outros.

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 de construtores de serialização para detalhes sobre formato de saída.

Adicionado na versão 0.5.

class sphinxcontrib.serializinghtml.PickleHTMLBuilder[código fonte]

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 de construtores de serialização para detalhes sobre formato de saída.

name = 'pickle'

O nome do construtor, para a opção de linha de comando -b.

O antigo nome web também continua funcionando.

format = 'html'

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

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

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

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

class sphinxcontrib.serializinghtml.JSONHTMLBuilder[código fonte]

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 de construtores de serialização para detalhes sobre formato de saída.

name = 'json'

O nome do construtor, para a opção de linha de comando -b.

format = 'html'

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

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

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

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[código fonte]

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'

O nome do construtor, para a opção de linha de comando -b.

format = ''

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

supported_image_types: list[str] = []

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

Adicionado na versão 1.1.

class sphinx.builders.changes.ChangesBuilder[código fonte]

Este construtor produz uma visão geral em HTML de todas as diretivas versionadded, versionchanged, deprecated e versionremoved para version atual. Isso é útil para gerar um arquivo de changelog, por exemplo.

name = 'changes'

O nome do construtor, para a opção de linha de comando -b.

format = ''

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

supported_image_types: list[str] = []

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

class sphinx.builders.dummy.DummyBuilder[código fonte]

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

name = 'dummy'

O nome do construtor, para a opção de linha de comando -b.

supported_image_types: list[str] = []

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

Adicionado na versão 1.4.

class sphinx.builders.linkcheck.CheckExternalLinksBuilder[código fonte]

Esse construtor busca links externos em todos os documentos, 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'

O nome do construtor, para a opção de linha de comando -b.

format = ''

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

supported_image_types: list[str] = []

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

Alterado na versão 1.5: Desde Sphinx 1.5, o construtor linkcheck usa o módulo requests.

Alterado na versão 3.4: O construtor linkcheck tenta acessar links novamente quando os servidores aplicam limites de taxa de acesso.

class sphinx.builders.xml.XMLBuilder[código fonte]

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

name = 'xml'

O nome do construtor, para a opção de linha de comando -b.

format = 'xml'

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

supported_image_types: list[str] = []

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

Adicionado na versão 1.2.

class sphinx.builders.xml.PseudoXMLBuilder[código fonte]

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'

O nome do construtor, para a opção de linha de comando -b.

format = 'pseudoxml'

O formato de saída do construtor ou ‘’, se nenhuma saída de documento for produzida.

supported_image_types: list[str] = []

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

Adicionado na versão 1.2.

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

Detalhes de construtores 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 embutida que implementa o interface de serialização com pickle.

Os arquivos por arquivo fonte têm extensões de out_suffix, e são organizadas em diretórios como estão os arquivos fonte. Eles são desserializados para um dicionário, ou estrutura similar, 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 marcação).

toc

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

display_toc

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

current_page_name

O nome do documento do arquivo atual.

parents, prev e next

Informações sobre os capítulos relacionados na árvore de TOC. Cada relação é um dicionário 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 serializado com pickle 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 serializações com pickle isso sempre será '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 na documentação. É uma lista com estas entradas:

  • Uma lista de nomes de documentos (docnames) indexados.

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

  • Um dicionário mapeando raízes de palavras (processadas por tratamento de 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 na desserialização com pickle.