Configuração¶

O diretório de configuração deve conter um arquivo chamado conf.py. Esse arquivo (contendo código Python) é chamado “arquivo de configuração da construção” e (geralmente) contém toda configuração necessária para personalizar o comportamento das entradas e saídas do Sphinx.

Um arquivo opcional docutils.conf pode ser adicionado ao diretório de configuração para ajustar a configuração do Docutils se não for substituído ou definido pelo Sphinx.

O arquivo de configuração é executado com código Python em tempo de construção (usando importlib.import_module(), e com o diretório corrente sendo definico como diretório base) e suporta a execução arbitrária de códigos complexos. Sphinx então faz a leitura de simples nomes de arquivos do namespace como sua configuração.

Pontos importantes a notar:

Se não documentado de outra maneira, valores devem ser strings e seus conteúdos padrão são strings vazias.
O termo “nome totalmente qualificado” refere-se a uma string que nomeia um objeto Python importável dentro de um módulo; por exemplo:, o "sphinx.builders.Builder" quer dizer a classe Builder no módulo sphinx.builders.
Lembrar que o nome do documento usa / como separador do caminho e não contém o nome da extensão do arquivo.
Já que conf.py é lido como um arquivo Python, as regras usuais se aplicam para codificação e suporte Unicode.
O conteúdo do namespace config é obtido (é assim que Sphinx pode encontrar modificações externas da configuração), portando não pode conter valores impossíveis de interpretação – remova esses no namespace com o comando del conforme apropriado. Módulos são removidos automaticamente, portanto não precisa usar del após uso em seus comandos import.
Existe um objeto especial chamado tags disponível no arquivo config. Pode ser usado para consultar e modificar tags (ver Incluindo conteúdo baseado em tags). Usar tags.has('tag') para consultar e tags.add('tag') e tags.remove('tag') para atualizar. Note que o construtor corrent não está disponível em conf.py, quando foi criado após o construtor ser inicializado.

Informação do Projeto¶

project¶: Documentar nome do Projeto.

author¶: O nome do autor(es) do documento. O padrão é 'unknown'.

copyright¶: Informação de direito autoral no estilo '2008, Author Name'.

Alterado na versão 7.1: The value may now be a sequence of copyright statements in the above form, which will be displayed each to their own line.

project_copyright¶: Um apelido para copyright.

Novo na versão 3.5.

version¶: Versão abrangente, usada em lugar de |version|. Por exemplo na documentação Python, pode ser algo como 2.6.

release¶

Versão completa projeto, usada em substituição para |release| e em modelos HTML. Por exemplo, para documentação Python, pode conter algo como 2.6.0rc1.

Se não necessitar separação entre version e release, apenas configure ambos para mesmo valor.

Configuração Geral¶

extensions¶

Uma lista de strings que são nomes de módulos de extensões. Essas podem ser extensões nativas do Sphinx (chamadas sphinx.ext.*) e outras configuradas.

Notar que sys.path pode ser extendidodentro do arquivo conf se suas extensões estão em outro diretório – mas confirme o caminho real. Se o caminho de sua extensão é relativo ao diretório de configuração, usar os.path.abspath() como:

import sys, os

sys.path.append(os.path.abspath('sphinxext'))

extensions = ['extname']

Dessa maneira, pode ser carregada a extensão chamada extname do subdiretório sphinxext.

O próprio arquivo de configuração pode ser uma extensão; para isso é necessário usar a função setup() no arquivo.

source_suffix¶

A extensão de arquivos fonte. Sphinx considera os arquivos com estes sufixos como fonte. O valor pode ser um dicionário mapeando extensões de arquivos para tipos de arquivos. Por exemplo:

source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'restructuredtext',
    '.md': 'markdown',
}

Por padrão, Sphinx somente tem suporte a tipos de arquivo 'restructuredtext'. Pode adicionar um novo tipo de fonte nas extensões permitidas. Leia a documentação da extensão para conhecer o tipo de arquivo que a extensão tem suporte.

O valor também pode ser uma lista de extensões de arquivo: então o Sphinx irá considerar que todos eles mapeiam para o tipo de arquivo 'restructuredtext'.

O padrão é {'.rst': 'restructuredtext'}.

Nota

extensões de arquivo devem começar com um ponto (por exemplo, .rst).

Alterado na versão 1.3: Pode agora ser uma lista de extensões.

Alterado na versão 1.8: Suporte a tipo de arquivo

source_encoding¶: A codificação de todos arquivos fonte reST. O código recomendado e valor padrão é 'utf-8-sig'.

Novo na versão 0.5: Anteriormente, Sphinx aceitava somente fontes UTF-8.

source_parsers¶

Se informado o dicionário de classes passadas para diferentes sufixos de fontes. As chaves são sufixos, os valores podem ser uma classe ou uma string informando o nome completamente qualificado da classe informada. A classe passada pode ser docutils.parsers.Parser ou sphinx.parsers.Parser. Arquivos com sufixos que não estão no dicionário serão tratados como reStructuredText padrão.

Por exemplo:

source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}

Nota

Consulte Markdown para mais informações sobre o uso do Markdown com o Sphinx.

Novo na versão 1.3.

Obsoleto desde a versão 1.8: Agora o Sphinx fornece um método API Sphinx.add_source_parser() para registrar analisador de fonte. Use esse método.

master_doc¶: O mesmo que root_doc.

Alterado na versão 4.0: Renomeado master_doc para root_doc.

root_doc¶: O nome de documento do documento “root”, isto é, o documento que contém a diretiva raiz toctree. O padrão é 'index'.

Alterado na versão 2.0: O padrão foi alterado para 'index' de 'contents'.

Alterado na versão 4.0: Renomeado root_doc de master_doc.

exclude_patterns¶

A list of glob-style patterns [1] that should be excluded when looking for source files. They are matched against the source file names relative to the source directory, using slashes as directory separators on all platforms.

Padrões de exemplo:

'library/xml.rst' – ignores the library/xml.rst file
'library/xml' – ignora o diretório de library/xml
'library/xml*' – ignora todos os arquivos e diretórios iniciando com library/xml
'**/.svn' – ignora todos diretórios .svn

exclude_patterns também é consultado quando buscando por arquivos estáticos no html_static_path e html_extra_path.

Novo na versão 1.0.

include_patterns¶

A list of glob-style patterns [1] that are used to find source files. They are matched against the source file names relative to the source directory, using slashes as directory separators on all platforms. The default is **, meaning that all files are recursively included from the source directory.

Padrões de exemplo:

'**' – all files in the source directory and subdirectories, recursively
'library/xml' – just the library/xml directory
'library/xml*' – all files and directories starting with library/xml
'**/doc' – all doc directories (this might be useful if documentation is co-located with source files)

Novo na versão 5.1.

templates_path¶: A lista de caminhos que contêm modelos extras (ou modelos que sobrepõe temas internos ou específicos do tema). Caminhos relativos são tratados como relativos ao diretório da configuração.

Alterado na versão 1.3: Como esses arquivos não devem ser construídos, são automaticamente adicionados em exclude_patterns.

template_bridge¶: String com nome totalmente qualificado de chamável (ou simplesmente uma classe) que retorna uma instância de TemplateBridge. Essa instância é então usada para renderizar a criação de documentos HTML ou de outros construtores (construtor corrente). (Note que a ligação do modelo do tema deve comportar HTML se temas são usados.)

rst_epilog¶

Uma string de reStructuredText que pode ser incluída ao final de todo fonte que for lido. Isso é possível adicionar uma substituição que estará disponível em todo arquivo (outro como rst_prolog). Exemplo:

rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""

Novo na versão 0.6.

rst_prolog¶

Uma string de reStructuredText que será incluída no início de cada arquivo fonte que é lido. Este é um local possível para adicionar substituições que devem estar disponíveis em todos os arquivos (outro sendo rst_epilog). Um exemplo:

rst_prolog = """
.. |psf| replace:: Python Software Foundation
"""

Novo na versão 1.0.

primary_domain¶: O nome do domínio padrão. Também pode ser None para desabilitar um domínio padrão. O padrão é 'py'. Esses objetos em outros domínios (se o nome do domínio é fornecido explicitamente ou selecionado por uma diretiva default-domain) terão o nome do domínio explicitamente prefixado quando nomeado (por exemplo, quando o domínio padrão é C, funções Python serão nomeadas “função Python”, não apenas “função”).

Novo na versão 1.0.

default_role¶

O nome de uma regra reST (nativa ou extensão Sphinx) para usar role padrão, isso é, o texto marcado `como esse`. Pode ser configurado para 'py:obj' para referência cruzada do `filtro`. O padrão é None que não reassinala a role padrão.

The default role can always be set within individual documents using the standard reST default-role directive.

Novo na versão 0.4.

keep_warnings¶

Se true, mantém avisos como parágrafos de “mensagens de sistema” nos documentos construídos. A menos que isso seja definido, avisos são sempre exibidos na saída padrão quando sphinx-build for executado.

O padrão é False, o comportamento pré-0.5 foi sempre mantê-los.

Novo na versão 0.5.

suppress_warnings¶

Uma lista arbitrária, dos tipos de mensagens de aviso que devem ser suprimidas.

Sphinx suporta os seguintes tipos de alertas:

app.add_node
app.add_directive
app.add_role
app.add_generic_role
app.add_source_parser
autosectionlabel.*
download.not_readable
epub.unknown_project_files
epub.duplicated_toc_entry
i18n.inconsistent_references
index
image.not_readable
ref.term
ref.ref
ref.numref
ref.keyword
ref.option
ref.citation
ref.footnote
ref.doc
ref.python
misc.highlighting_failure
toc.circular
toc.excluded
toc.not_readable
toc.secnum

Você pode escolher entre esses tipos. Você também pode fornecer apenas o primeiro componente para excluir todos os avisos anexados a ele.

Atualmente essa opção é considerada experimental.

Novo na versão 1.4.

Alterado na versão 1.5: Adic. misc.highlighting_failure

Alterado na versão 1.5.1: Adic. epub.unknown_project_files

Alterado na versão 1.6: Adic. ref.footnote

Alterado na versão 2.1: Adicionada autosectionlabel.*

Alterado na versão 3.3.0: Adicionada epub.duplicated_toc_entry

Alterado na versão 4.3: Adicionado toc.excluded e toc.not_readable

Novo na versão 4.5:

Adicionado i18n.inconsistent_references

Novo na versão 7.1: Added index warning type.

needs_sphinx¶: Se configurado como uma string de versão major.minor como '1.1', Sphinx irá comparar isso com a sua versão e recusará construir se sua versão for muito antiga. O padrão é nenhum requerimento.

Novo na versão 1.0.

Alterado na versão 1.4: também aceita string micro versão

needs_extensions¶

O valor pode ser dicionário especificando os requerimentos das extensões extensions; ex: needs_extensions = {'sphinxcontrib.something': '1.5'}. A string da versão deve ser no formato major.minor. Requerimentos não precisam ser expecificado para todas extensões, apenas para as que devem ser verificadas.

Isso requer extensões que especificam sua versão para o Sphinx (ver Sphinx Extensions API para como usar isso).

Novo na versão 1.3.

manpages_url¶

Um URL para fazer referência cruzada aos papéis manpage. Se estiver definido para https://manpages.debian.org/{path}, o papel :manpage:`man(1)` será vinculado a <https://manpages.debian.org/man(1)>. Os padrões disponíveis são:

page - página manual (man)
section - a seção do manual (1)
path - a página original e a seção especificada do manual (man(1))

Também suporta páginas especificadas como man.1.

Nota

Atualmente afeta somente geração HTML mas pode ser expandido no futuro.

Novo na versão 1.7.

nitpicky¶: Se true (verdadeiro), Sphinx irá avisar sobre todas referências onde o alvo não foi encontrado. Padrão é False. Pode ser ativado temporáriamente usando na linha de comando com -n.

Novo na versão 1.0.

nitpick_ignore¶: A set or list of (type, target) tuples (by default empty) that should be ignored when generating warnings in “nitpicky mode”. Note that type should include the domain name if present. Example entries would be ('py:func', 'int') or ('envvar', 'LD_LIBRARY_PATH').

Novo na versão 1.1.

Alterado na versão 6.2: Changed allowable container types to a set, list, or tuple

nitpick_ignore_regex¶

Uma versão estendida do nitpick_ignore, que interpreta as strings type e target como expressões regulares. Note que a expressão regular deve corresponder a toda a string (como se os marcadores ^ e $ tivessem sido inseridos.)

Por exemplo, (r'py:.*', r'foo.*bar\.B.*') irá ignorar avisos chatos para todas as entidades python que comecem com``’foo’`` e tenham 'bar.B' neles, tal como ('py:const', 'foo_package.bar.BAZ_VALUE') ou ('py:class', 'food.bar.Barman').

Novo na versão 4.1.

Alterado na versão 6.2: Changed allowable container types to a set, list, or tuple

numfig¶: Se verdadeiro, figuras, tabelas e bloco de códigos são automaticamente numerados, caso tenham legenda. Se a regra numref estivar habilitada. Abrange atualmente HTML e LaTeX. Padrão False.

Nota

O construtor LaTeX sempre assinala números onde essa opção é habilitada ou não

Novo na versão 1.3.

numfig_format¶

Um dicionário mapeando 'figure', 'table', 'code-block' e 'section' para strings que são usadas para o formato de números de figura. Como um caractere especial, %s será substituído com o número da figura.

O padrão é usar 'Fig. %s' para 'figure', 'Table %s' para 'table', 'Listing %s' para 'code-block' e 'Section %s' para 'section'.

Novo na versão 1.3.

numfig_secnum_depth¶

se configurado para 0, figuras, tabelas e bloco de código são continuamente numerados iniciando em 1.
se 1 (padrão) números serão x.1, x.2, … com x o número da seção (nível superior de seção); em x. se não houver secão). Isso naturalmente se aplica, somente se numeração foi ativada através da opção :numbered: da diretiva toctree .
2 significa que números serão x.y.1, x.y.2, … se existirem em uma sub-seção (mas aparedcem x.1, x.2, … se existirem sob uma seção e 1, 2, … se não existirem em nenhuma seção nível superior.)
etc.

Novo na versão 1.3.

Alterado na versão 1.7: O construtor LaTeX obedece essa configuração (se numfig é True).

smartquotes¶

Se verdadeiro, a `Docutils Smart Quotes transform`__, originalmente baseada em `SmartyPants`__ (limitada ao Inglês) e atualmente aplica-se para diversos idiomas, será usada para converter aspas e traços para entidades tipograficamente corretas. Padrão: True.

Novo na versão 1.6.6: Substitui o obsoleto html_use_smartypants. Aplica-se por padrão para todos os construtores exceto man e text (ver smartquotes_excludes.)

Arquivo `docutils.conf`__ localizado no diretório de configuração (ou arquivo global ~/.docutils ) é respeitado incondicionalmente se ele desativa aspas diferentes através da opção correspondente `Docutils option`__. Mas se for ativada então smartquotes , não prevalece.

smartquotes_action¶: Esta string personaliza a transformação Smart Quotes (aspas inteligentes). Veja o arquivo smartquotes.py no repositório Docutils para detalhes. O padrão 'qDe' educa os caracteres normais de aspas (quote) ", ', travessão e meia-risca (em- e en-Dashes) ---, --, e reticências (ellipses) ....

Novo na versão 1.6.6.

smartquotes_excludes¶

Um dict cujo padrão é:

{'languages': ['ja'], 'builders': ['man', 'text']}

Cada entrada fornece uma condição suficiente para ignorar a configuração smartquotes e desativar a transformação Smart Quotes. As chaves aceitas são como acima 'builders' ou 'languages'. Os valores são listas.

Nota

Atualmente, em caso de chamada do make com múltiplos alvos, o primeiro nome será o único validado nas opções 'builders' e decidirá por todos. Também um make text seguido por make html aninhado será emitido no formato make text O="-E" para forçar a transmissão dos arquivos fonte, como cache que já foi transformado. De outra maneira o requerimento não se realizará no uso do sphinx-build como cache (que é o uso padrão) dos arquivos fontes submetidos para cada construtor.

Dica

Uma maneira alternativa de efetivamente desativar (ou personalizar) as aspas inteligentes para um determinado construtor, por exemplo, latex, é usar o make desta maneira:

make latex O="-D smartquotes_action="

This can follow some make html with no problem, in contrast to the situation from the prior note.

Novo na versão 1.6.6.

user_agent¶: Um User-Agent de Sphinx. É usado para um cabeçalho no acesso HTTP (ex.: linkcheck, intersphinx e assim por diante). O padrão é "Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z".

Novo na versão 2.3.

tls_verify¶: Se verdadeiro, Sphinx verifica certificação do servidor. Padrão True.

Novo na versão 1.5.

tls_cacerts¶: Caminho para certificação do arquivo do CA ou caminho para o diretório que contem os certificados. Isso permite o dicionário mapear nome do host para o caminho do certificado. O certificado é usado para verificar a certificação do servidor.

Novo na versão 1.5.

Dica

Sphinx usa requests como uma biblioteca HTTP internamente. Portanto, Sphinx consulta um arquivo de certificação no diretório apontado pela variável de ambiente REQUESTS_CA_BUNDLE se tls_cacerts não estiver definida.

today¶

today_fmt¶

esses valores determinam como o formato da data atual, usado em detrimento de |today|.

Se configurar today para um valor não vazio, ele será usado.
Caso contrário, horário corrente será usado no formato time.strftime() e o formato today_fmt.

O padrão é agora today e um today_fmt de '%b %d, %Y' (ou se tradução estiver habilitada com language, um formato será selecionado na localidade equivalente).

highlight_language¶

A linguagem padrão para realçar o código-fonte. O padrão é 'default'. É semelhante ao 'python3'; é basicamente um superconjunto de 'python', mas ele cai para 'none' sem aviso de falha. 'python3' e outras linguagens emitem aviso se falharem.

O valor deve ser um nome de lexador válido do Pygments, veja :ref:`code-examples: para mais detalhes.

Novo na versão 0.5.

Alterado na versão 1.4: O padrão agora é 'default'. Se você preferir o realce apenas de Python 2, você pode configurá-lo de volta para 'python'.

highlight_options¶

Um dicionário que mapeia nomes de idiomas para opções para os módulos analisadores léxicos de Pygments. Estes são específicos do analisador léxico; para as opções compreendidas por cada um, consulte a documentação do Pygments.

Exemplo:

highlight_options = {
  'default': {'stripall': True},
  'php': {'startinline': True},
}

Um único dicionário de opções também é permitido. Em seguida, é reconhecido como opções para o analisador léxico especificado por highlight_language:

# configuration for the ``highlight_language``
highlight_options = {'stripall': True}

Novo na versão 1.3.

Alterado na versão 3.5: Permite configurar opções de realce para várias linguagens

pygments_style¶: O nome do estilo usado para enfatizar código fonte com Pygments. Se não configurado usa estilo do tema ou ‘sphinx’` é selecionado na saída HTML.

Alterado na versão 0.3: Se o valor é completamente qualificado como um nome configurado de estilo de classe Pygments, então será usado como estilo personalizado.

maximum_signature_line_length¶

If a signature’s length in characters exceeds the number set, each parameter within the signature will be displayed on an individual logical line.

When None (the default), there is no maximum length and the entire signature will be displayed on a single logical line.

A ‘logical line’ is similar to a hard line break—builders or themes may choose to ‘soft wrap’ a single logical line, and this setting does not affect that behaviour.

Domains may provide options to suppress any hard wrapping on an individual object directive, such as seen in the C, C++, and Python domains (e.g. py:function:single-line-parameter-list).

Novo na versão 7.1.

add_function_parentheses¶: Booleano que decide onde parenteses são anexados a funções ou regra do texto (ex: conteúdo de :func:`input`) para significar que o nome é chamado. Padrão para True.

add_module_names¶: Booleano que decide sobre nomes dos módulos serão prefixados a todos nomes object (para tipos de objetos onde “modulo” é definido), e.g. para py:function. Padrão é True.

toc_object_entries¶: Create table of contents entries for domain objects (e.g. functions, classes, attributes, etc.). Default is True.

toc_object_entries_show_parents¶

A string that determines how domain objects (e.g. functions, classes, attributes, etc.) are displayed in their table of contents entry.

Use domain to allow the domain to determine the appropriate number of parents to show. For example, the Python domain would show Class.method() and function(), leaving out the module. level of parents. This is the default setting.

Use hide to only show the name of the element without any parents (i.e. method()).

Use all to show the fully-qualified name for the object (i.e. module.Class.method()), displaying all parents.

Novo na versão 5.2.

show_authors¶: Booleano que decide diretivas para diretório codeauthor e sectionauthor quanto a geração nos arquivos.

modindex_common_prefix¶: Lista de prefixos que serão ignorados para classificação índice módulos Python (ex: se configurado ['foo.'], então foo.bar é exibido sob o B, não no F). Isso pode ser útil quando seu projeto tem um único pacote. Atualmente funcionada só para o construtor HTML. Padrão é [].

Novo na versão 0.6.

trim_footnote_reference_space¶: Espaços antes das referências de rodapé são necessários para o parser reST para reconhecer notas de rodapé, mas não tem aparência boa na saída.

Novo na versão 0.6.

trim_doctest_flags¶: Se verdadeiro, doctest marca (comentários como # doctest: FLAG, ...) ao final das linhas e marcas <BLANKLINE> são removidas para todos blocos de código exibidos em sessões interativas Python (ex.. doctests). Padrão “True”. Ver a extensão doctest para mais possibilidades na inclusão de doctests.

Novo na versão 1.0.

Alterado na versão 1.1: Agora també remove <BLANKLINE>.

strip_signature_backslash¶: O padrão é False. Quando a remoção da barra invertida está habilitada, então cada ocorrência de \\ em uma diretiva de domínio será alterada para \, mesmo dentro de literais de string. Este era o comportamento antes da versão 3.0, e definir esta variável como True irá restabelecer esse comportamento.

Novo na versão 3.0.

option_emphasise_placeholders¶: Default is False. When enabled, emphasise placeholders in option directives. To display literal braces, escape with a backslash (\{). For example, option_emphasise_placeholders=True and .. option:: -foption={TYPE} would render with TYPE emphasised.

Novo na versão 5.1.

Opções para internacionalização¶

Essa opção influencia Sphinx Suporte Nativo a Idiomas. Ver documentação Internacionalização, para maiores detalhes.

language¶

The code for the language the docs are written in. Any text automatically generated by Sphinx will be in that language. Also, Sphinx will try to substitute individual paragraphs from your documents with the translation sets obtained from locale_dirs. Sphinx will search language-specific figures named by figure_language_filename (e.g. the German version of myfigure.png will be myfigure.de.png by default setting) and substitute them for original figures. In the LaTeX builder, a suitable language will be selected as an option for the Babel package. Default is 'en'.

Novo na versão 0.5.

Alterado na versão 1.4: Suporte substituição figura

Alterado na versão 5.0.

Idiomas atualmente suportados são:

ar – Árabe
bg – Búlgaro
bn – Bengali
ca – Catalão
cak – Caqchiquel
cs – Czech
cy – Galês
da – Dinamarquês
de – Alemão
el – Grego
en – English (default)
eo – Esperanto
es – Espanhol
et – Estoniano
eu – Basco
fa – Iraniano
fi – Finlandês
fr – Francês
he – Hebreu
hi – Hindi
hi_IN – Hindi (Índia)
hr – Croata
hu – Húngaro
id – Indonésio
it – Italiano
ja – Japonês
ko – Koreano
lt – Lituano
lv – Letão
mk – Macedônio
nb_NO – Norueguês Bokmal
ne – Nepalês
nl – Holandês
pl – Polonês
pt – Português
pt_BR – Português do Brasil
pt_PT – Português Portugal
ro – Romeno
ru – Russo
si – Sinhala
sk – Eslovêno
sl – Eslovênia
sq – Albanês
sr – Sérvio
sr@latin – Sérvio (Latim)
sr_RS – Sérvio (Cirílico)
sv – Sueco
ta – Tâmil
te – Telugu
tr – Turco
uk_UA – Ucraniano
ur – Urdu
vi – Vietnamita
zh_CN – Chinês Simplificado
zh_TW – Chinês Traditional

locale_dirs¶

Novo na versão 0.5.

Diretórios nos quais a pesquisa adicional do catálogo de mensagem (ver language), relativos ao diretório fonte. Os diretórios desse caminho de busca será usado pelo módulo padrão gettext.

Mensagens Internas do Sphinx são recuperadas de um domínio sphinx; se adicionar o arquivo ./locale nessa configuração, o catálogo de mensagem (compilado no formato .po usando o programa msgfmt) deve estar em ./locale/language/LC_MESSAGES/sphinx.mo. O domínio individual dos documentos depende de gettext_compact.

O padrão é ['locales'].

Nota

A opção -v para o comando sphinx-build é útil para verificar se a configuração locale_dirs funciona conforme o esperado. Ele emite mensagens de depuração se o diretório do catálogo de mensagens não for encontrado.

Alterado na versão 1.5: Usar diretório locales como valor padrão.

gettext_allow_fuzzy_translations¶: Se verdadeiro, as mensagens “difusas” nos catálogos de mensagens são usadas para tradução. O padrão é False.

Novo na versão 4.3.

gettext_compact¶

Novo na versão 1.1.

Se verdadeiro, um domínio de documento texto do docname e se for o nível topo arquivo de projeto ou seu diretório base.

Se definido como string, todo o domínio de texto do documento é esta string, fazendo com que todos os documentos usem um único domínio de texto.

Por padrão, o documento markup/code.rst termina no domínio texto markup. Com esta opção ativada para False será markup/code.

Alterado na versão 3.3: O valor string agora é aceito.

gettext_uuid¶

Se verdadeiro, Sphinx gerá informação uuid para rastrear versão os catálogos de mensagnes. Usado para:

Adicionar linha uid para cada msgid nos arquivos .pot.
Calcular similaridade entre novas msgids e previas salvas em antigas msgids. Esse cálculo leva algum tempo.

Se deseja acelerar o cálculo, pode usar python-levenshtein pacote de 3. escrito em C usando o comando pip install python-levenshtein.

O padrão é False.

Novo na versão 1.3.

gettext_location¶

Se verdadeiro, Sphinx gera informação para tradução de mensagens em catalogos de mensagens.

O padrão é True.

Novo na versão 1.3.

gettext_auto_build¶

Se verdadeiro, Sphinx constrói arquivo mo (binario) para cada catálogo de mensagem.

O padrão é True.

Novo na versão 1.3.

gettext_additional_targets¶

Para especificar nome para habilitar gettext extraindo e traduzindo aplicando i18n adicionalmente. Pode ser especificado os nomes:

índice:: index terms
Literal-block:: blocos literais (anotação :: e diretiva code-block)
Doctest-block:: bloco doctest
Raw:: conteúdo bruto
imagem:: uri de imagem/figura

Por exemplo: gettext_additional_targets = ['literal-block', 'image'].

Padrão é [].

Novo na versão 1.3.

Alterado na versão 4.0: O texto alternativo da imagem é traduzido por padrão.

figure_language_filename¶

O nome do arquivo de imagem no idioma específico. O padrão é {root}.{idioma}{ext}. Será expandido para diretório/arquivo.en.png derivado de .. image:: diretório/nomearquivo.png. Os códigos disponíveis são:

{root} - O nome do arquivo, incluindo componentes de caminho, porem sem a extensão do arquivo, ex. diretório/arquivo
{path} - o caminho do diretório do nome do arquivo, com barra final se não for vazio, ex. diretório/
{docpath} - o componente do caminho do diretório para o documento atual, com uma barra se não estiver vazio.
{basename} - nome do arquivo sem o caminho do diretório e sem a extensão do arquivo, ex. arquivo
{ext} - a extensão do arquivo, ex. .png
{language} - idioma da tradução, ex. en

Por exemplo, configurado isso para {path}{language}/{basename}{ext} irão ser expandidas para dirname/en/filename.png.

Novo na versão 1.4.

Alterado na versão 1.5: Adic. {path} e {basename} termos.

Alterado na versão 3.2: Adicionado o token {docpath}.

translation_progress_classes¶

Control which, if any, classes are added to indicate translation progress. This setting would likely only be used by translators of documentation, in order to quickly indicate translated and untranslated content.

True: add translated and untranslated classes to all nodes with translatable content.
translated: only add the translated class.
untranslated: only add the untranslated class.
False: do not add any classes to indicate translation progress.

O padrão é False.

Novo na versão 7.1.

Opções para Math¶

Estas opções influenciam notações Math.

math_number_all¶: Defina essa opção para True se deseja exibir numeração. O padrão é False.

math_eqref_format¶

Uma string usada para formatar os rótulos das referências às equações. O marcador de posição {number} representa o número da equação.

Exemplo: 'Eq.{number}' é renderizado como, por exemplo, Eq.10.

math_numfig¶: Se Verdadeiro, equações matemáticas serão exibidas como numeradas através das páginas quando numfig estiver habilitada. A configuração numfig_secnum_depth será respeitada. Será usada eq, não será usada numref, role deve ser usada para referenciar número de equações. Padrão é Verdadeiro.

Novo na versão 1.7.

Opções para saída HTML¶

Essas opções influenciam HTML bem como Saída HTML Help e outros construtores que usam classe Sphinx HTMLWriter.

html_theme¶: O “tema” que a saída HTML deve usar. Veja a seção sobre temas. O padrão é 'alabaster'.

Novo na versão 0.6.

html_theme_options¶: Dicionário de opções que influenciam aparência e comportamento do tema selecionado. São específicos para tema. Para opções inteligíveis dos temas veja this section.

Novo na versão 0.6.

html_theme_path¶: Lista de caminhs que contém temas configurados, pode ser subdiretórios ou arquivos zip. Relativo ao caminho do diretório de configuração.

Novo na versão 0.6.

html_style¶: Folha de estilo para páginas HTML. Arquivo com esse nome deve existir no caminho static/, ou nos caminhos configuráveis html_static_path. Padrão é folha de estilo para o tema escolhido. Se desejar adicionar ou sobrepôr apenas alguns parâmetros usar CSS @import para importar folha de estilos.

html_title¶: O “título” para documentação HTML gerada pelos modelos Sphinx. Anexado na tag <title> das páginas individuais e usada na barra de navegação do elemento “superior”. Padrão para 'documentação <project> v<revision> '.

html_short_title¶: Um “título” mais curto para os documentos HTML. Isso é usado para links no cabeçalho e nos documentos de Ajuda em HTML. Se não for fornecido, o padrão é o valor de html_title.

Novo na versão 0.4.

html_baseurl¶: O URL base que aponta para a raiz da documentação HTML. É usado para indicar o local do documento usando The Canonical Link Relation. Padrão: ''.

Novo na versão 1.8.

html_codeblock_linenos_style¶

O estilo de números de linha para blocos de código.

'table' – exibe números de linha usando a tag <table>
'inline' – exibe números de linha usando a tag <span> (padrão)

Novo na versão 3.2.

Alterado na versão 4.0: Tem como padrão 'inline'.

Obsoleto desde a versão 4.0.

html_context¶: Dicionário de valores para passar ao mecanismo contexto para todas páginas. Valores simples podem ser usados nesse dicionário através da opção -A da linha de comando do sphinx-build.

Novo na versão 0.5.

html_logo¶: Se fornecido, deve ser o nome de um arquivo de imagem (caminho relativo ao diretório de configuração) que é o logotipo dos documentos, ou URL que aponta um arquivo de imagem para o logotipo. Ele é colocado na parte superior da barra lateral; sua largura, portanto, não deve exceder 200 pixels. Padrão: None.

Novo na versão 0.4.1: O arquivo de imagem será copiado para diretório _static da saída HTML, mas somente se o arquivo não existir nesse local.

Alterado na versão 4.0: Também aceita a URL do arquivo de logotipo.

html_favicon¶: Se fornecido, deve ser o nome de um arquivo de imagem (caminho relativo ao diretório de configuração) que é o favicon dos documentos, ou URL que aponta um arquivo de imagem para o favicon. Os navegadores modernos usam isso como ícone para abas, janelas e favoritos. Deve ser um arquivo de ícone no estilo do Windows (.ico), que tem 16x16 ou 32x32 pixels de tamanho. Padrão: None.

Novo na versão 0.4: O arquivo de imagem será copiado para diretório _static da saída HTML, mas somente se o arquivo não existir nesse local.

Alterado na versão 4.0: Também aceita a URL do favicon.

html_css_files¶

Uma lista de arquivos CSS. A entrada deve ser uma string nome de arquivo ou uma tupla contendo a string nome de arquivo e o dicionário de atributos. O nome de arquivo deve ser relativo ao html_static_path, ou um URI completo com esquema como https://example.org/style.css. Os atributos são usados para atributos da tag <link>. O padrão é uma lista vazia.

Exemplo:

html_css_files = ['custom.css',
                  'https://example.com/css/custom.css',
                  ('print.css', {'media': 'print'})]

As a special attribute, priority can be set as an integer to load the CSS file earlier or lazier step. For more information, refer Sphinx.add_css_file().

Novo na versão 1.8.

Alterado na versão 3.5: Suporte ao atributo de prioridade

html_js_files¶

Uma lista de filename JavaScript. A entrada deve ser uma string filename ou uma tupla contendo a string filename e o dicionário attributes. O filename deve ser relativo ao html_static_path ou uma URI completa com esquema como https://example.org/script.js. Os attributes são usados para atributos da tag 1. O padrão é uma lista vazia.

Exemplo:

html_js_files = ['script.js',
                 'https://example.com/scripts/custom.js',
                 ('custom.js', {'async': 'async'})]

As a special attribute, priority can be set as an integer to load the CSS file earlier or lazier step. For more information, refer Sphinx.add_css_file().

Novo na versão 1.8.

Alterado na versão 3.5: Suporte ao atributo de prioridade

html_static_path¶

Lista de caminhos que contém arquivos estáticos (como folhas de estilo ou arquivos script). Relativos ao diretório de config. São copiados para o arquivo saída _static diretório após arquivos estáticos de tema, portante um arquivo chamado default.css será sobreposto pelo arquivo tema default.css.

Como esses arquivos não são destinados para serem construídos, eles são automaticamente excluídos dos arquivos fontes.

Nota

Por razões de segurança, dotfiles em html_static_path não serão copiados. Se desejar copiá-los intencionalmente, adicione cada caminho de arquivo a esta configuração:

html_static_path = ['_static', '_static/.htaccess']

Outra forma de fazer isso, você também pode usar html_extra_path. Permite copiar dotfiles nos diretórios.

Alterado na versão 0.4: O caminho em html_static_path agora pode conter subdiretórios.

Alterado na versão 1.0: As entradas em html_static_path pode ser arquivos simples.

Alterado na versão 1.8: Os arquivos em html_static_path são excluídos dos arquivos fonte.

html_extra_path¶

A lista de caminhos que contem arquivos extras, não diretamente relacionados com a documentação,como robots.txt ou .htaccess. Caminhos Relativos são obtidos no diretório de configuração. Serão copiados para o diretório de saida. Irão sobrepor arquivo já existente com o mesmo nome.

Como esses arquivos não são destinados para serem construídos, eles são automaticamente excluídos dos arquivos fontes.

Novo na versão 1.2.

Alterado na versão 1.4: Os dotfiles no diretório extra serão copiados para o diretório de saída. E se refere am exclude_patterns sobre a cópia de arquivos e diretórios extras, e ignora se o caminho corresponde aos padrões.

html_last_updated_fmt¶: If this is not None, a ‘Last updated on:’ timestamp is inserted at every page bottom, using the given strftime() format. The empty string is equivalent to '%b %d, %Y' (or a locale-dependent equivalent).

html_use_smartypants¶: Se verdadeiro, aspas e traços são convertidos para entidades tipograficamente corretas. Padrão True.

Obsoleto desde a versão 1.6: Para desabilitar aspas smart, usar smartquotes.

html_permalinks¶: Add link anchors for each heading and description environment. Default: True.

Novo na versão 3.5.

html_permalinks_icon¶: Text for link anchors for each heading and description environment. HTML entities and Unicode are allowed. Default: a paragraph sign; ¶

Novo na versão 3.5.

html_sidebars¶

Modelo configurável de barra lateral, deve ser um dicionário que mapeia nomes de documentos a nomes de modelos.

As chaves podem conter padrões estilo global [1], nos casos onde os documentos que atenderem o critério, terão barras laterais especificadas. (Alerta é emitido quando mais de um padrão de estilo global combinar com um documento.)

Os valores pode ser listas ou simples strings.

O valor é uma lista, que especifica uma lista completa de modelos de barra lateral para inclusão. Se todas ou algumas barras laterais são incluídas, elas devem estar nessa lista também.

As barras laterais padrão (para documentos que não correspondem a nenhum padrão) são definidas pelo próprio tema. Os temas usam embutidos esses modelos por padrão: ['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'].
Se um valor é uma string simples, ele especifica uma barra lateral configurável a ser adicionada entre as entradas 'sourcelink.html' e 'searchbox.html'. Isso é para compatibilidade com versões Sphinx anteriores a 1.0.

Obsoleto desde a versão 1.7: um termo simples para html_sidebars será removido em 2.0

Modelos de barra lateral implícita são renderizados:

localtoc.html – tabela detalhada de conteúdos do documento atual
globaltoc.html – tabela esparça de conteúdo de todo o conjunto documento, modo encolhido
relations.html – links que apontam para o anterior e próximo documentos
sourcelink.html – link que aponta para o documento atual, se habilitado exibe html_show_sourcelink
searchbox.html – caixa “pesquisa rápida”

Exemplo:

html_sidebars = {
   '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
   'using/windows': ['windowssidebar.html', 'searchbox.html'],
}

Renderiza modelo configurável windowssidebar.html` e caixa de pesquisa dentro da barra lateral de um dado documento e renderiza barras laterais para outras páginas (exceto a tabela local de conteúdo TOC que será substituída pela TOC global).

Novo na versão 1.0: Habilidde em usar chaves globias e especificar múltiplas barras laterais.

Notar que esse valor só não tem efeito se o tema escolhido não possuir barra lateral, como os temas scrolls e haiku.

html_additional_pages¶

Modelos adicionais são renderizados para páginas HTML, devem ter um dicionário que mapeia nomes de documentos para nomes de modelos.

Exemplo:

html_additional_pages = {
    'download': 'customdownload.html',
}

Isso irá renderizar o modelo customdownload.html como página download.html.

html_domain_indices¶

Se verdadeiro, gera índices específicos do domínio em adição ao índice geral. Por ex. domínio Python, é um módulo índice global. Padrão é Verdadeiro.

Esse valor pode ser booleano ou lista de nomes de índices que devem ser gerados. Para encontrar o nome do índice para um índice específico, veja nome do arquivo HTML. Por exemplo: índice módulo Python tem nome 'py-modindex'.

Novo na versão 1.0.

html_use_index¶: Se Verdadeiro, adiciona um índice ao documento HTML. Padrão Verdadeiro.

Novo na versão 0.4.

html_split_index¶: Se verdadeiro, o índice é gerado novamente: quando uma simples página com todas entradas e quando uma página por letra inicial. Padrão é Falso.

Novo na versão 0.4.

html_copy_source¶: Se verdadeiro, fontes reSt são incluídos no construtor HTML como _sources/name. O padrão é True.

html_show_sourcelink¶: Se verdadeiro (e html_copy_source for verdadeiro também), links para fontes reST irão aparecer na barra lateral. O padrão é True.

Novo na versão 0.6.

html_sourcelink_suffix¶: Sufixo a ser anexado aos links de origem (veja html_show_sourcelink), a menos que eles já tenham este sufixo. O padrão é '.txt'.

Novo na versão 1.5.

html_use_opensearch¶: Se não estiver vazio, um arquivo de descrição OpenSearch será gerado e todas as páginas conterão uma tag <link> referente a ele. Como o OpenSearch não oferece suporte a URLs relativos para o local da página de pesquisa, o valor dessa opção deve ser o URL base do qual esses documentos são veiculados (sem barra final), por exemplo, "https://docs.python.org". O padrão é ''.

html_file_suffix¶: This is the file name suffix for generated HTML files, if set to a str value. If left to the default None, the suffix will be ".html".

Novo na versão 0.4.

html_link_suffix¶: Sufixo para links gerados para arquivos HTML. O padrão é o sufixo definido em html_file_suffix; pode ser modificado para suportar diferentes configurações de servidores web).

Novo na versão 0.6.

html_show_copyright¶: Se verdadeiro, “(C) Copyright …” é exibido no rodapé HTML. Padrão é True.

Novo na versão 1.0.

html_show_search_summary¶: Se true, o texto ao redor da palavra-chave é mostrado como resumo de cada resultado da pesquisa. O padrão é True.

Novo na versão 4.5.

html_show_sphinx¶: Se verdadeiro, exibe “Criado usando Sphinx” no rodapé HTML. Padrão é True.

Novo na versão 0.4.

html_output_encoding¶: Codificação arquivos de saída HTML. Padrão é 'utf-8'. Nota que esse nome da codificação deve ser válido no Python e no conjunto de caracteres.

Novo na versão 1.0.

html_compact_lists¶: Se verdadeiro, uma lista com todos os itens que consistem em um único parágrafo e/ou uma sublista com todos os itens etc… (definição recursiva) não usará o elemento <p> para nenhum de seus itens. Este é o comportamento padrão dos docutils. Predefinição: True.

Novo na versão 1.0.

html_secnumber_suffix¶: Sufixo para número de seções. Padrão: Default: ". ". para suprimir o ponto final no número das seções.

Novo na versão 1.0.

html_search_language¶

Idioma usado para geração do índice HTML da pesquisa texto. Padrão ao idiomal global selecionaod com language. Se não houver suporte ao idioma, "en" será usado para selecionar idioma Inglês.

Atualmente suporta esses idiomas:

da – Dinamarquês
nl – Holandês
en – Inglês
fi – Finlandês
fr – Francês
de – Alemão
hu – Húngaro
it – Italiano
ja – Japonês
no – Norueguês
pt – Português
ro – Romeno
ru – Russo
es – Espanhol
sv – Sueco
tr – Turco
zh – Chinês

Acelerando velocidade de montagem

Cada idioma (exceto Japonês) provê seu próprio algoritmo uso. Sphinx usa uma implementação Python por padrão. Pode ser escolhida a implementação C para acelerar a construção do arquivo índice.

PorterStemmer (en)
PyStemmer (todos os idiomas)

Novo na versão 1.1: Com suporte para en e ja.

Alterado na versão 1.3: Adicionado outros idiomas.

html_search_options¶

Um dicionário com opções de suporte a pesquisa em outros idiomas, vazio por padrão. O significado depende do idioma selecionado.

Em inglês não há opções.

Japonês suporte essas opções:

tipo:

type is dotted module path string to specify Splitter implementation which should be derived from sphinx.search.ja.BaseSplitter. If not specified or None is specified, 'sphinx.search.ja.DefaultSplitter' will be used.

Pode escolher entre esses módulos:

‘sphinx.search.ja.DefaultSplitter’:: Algoritmo TinySegmenter. Esse é o divisor padrão.
‘sphinx.search.ja.MecabSplitter’:: MeCab funcionalidade. Usar isso para dividir, ‘mecab’ ou biblioteca link dinâmico (‘libmecab.so’ para linux, ‘libmecab.dll’ para windows) é necessário.
‘sphinx.search.ja.JanomeSplitter’:: Associações para Janome. Para usar este divisor, Janome é exigido.

Obsoleto desde a versão 1.6: 'mecab', 'janome' e 'default' foram descontinuados. Para manter a compatibilidade, 'mecab', 'janome' e 'default' também são aceitos.

Valores das outras opções dependem de fragmentar o valor escolhido.

Opções para 'mecab':

dic_enc:: dic_enc option é a codificação do algoritmo MeCab.
dict:: dict option é o dicionário para usar algoritmo MeCab.
lib:: lib option é o nome da biblioteca para encontrar biblioteca MeCab via ctypes se o build do Python não estiver instalado.

Por exemplo:

html_search_options = {
    'type': 'mecab',
    'dic_enc': 'utf-8',
    'dict': '/path/to/mecab.dic',
    'lib': '/path/to/libmecab.so',
}

Opções para 'janome':

user_dic:: user_dic option é caminho para arquivo dicionário do Janome.
user_dic_enc:: user_dic_enc option é o código de página para arquivo dicionário especificado opção user_dic. Padrão ‘utf8’.

Novo na versão 1.1.

Alterado na versão 1.4: opções para html_search_options idioma Japonês é reorganizado e configurações serão usados por type settings.

Chinês suporta essas opções

dict – dicionário jieba caminho se deseja usar dicionário personalizado.

html_search_scorer¶: O nome do arquivo JavaScript (relativo ao diretório de configuração) que implementa rank resultados pesquisa. Se vazio, o padrão é usado.

Novo na versão 1.2.

html_scaled_image_link¶

If true, image itself links to the original image if it doesn’t have ‘target’ option or scale related options: ‘scale’, ‘width’, ‘height’. The default is True.

Document authors can disable this feature manually with giving no-scaled-link class to the image:

.. image:: sphinx.png
   :scale: 50%
   :class: no-scaled-link

Novo na versão 1.3.

Alterado na versão 3.0: Isso está desabilitado para imagens com a classe no-scaled-link

html_math_renderer¶: O nome da extensão math_renderer para saída HTML. O padrão é 'mathjax'.

Novo na versão 1.8.

html_experimental_html5_writer¶: A saída é processada com o escritor HTML5. O padrão é False.

Novo na versão 1.6.

Obsoleto desde a versão 2.0.

html4_writer¶: A saída é processada com o escritor HTML4. O padrão é False.

Opções para a saída Single HTML¶

singlehtml_sidebars¶: Os modelos personalizados da barra lateral devem ser um dicionário que mapeia nomes de documentos para nomes de modelos. E só permite uma chave chamada ‘index’. Todas as outras chaves são ignoradas. Para mais informações, consulte html_sidebars. Por padrão, é o mesmo que html_sidebars.

Opções para ajuda saída HTML¶

htmlhelp_basename¶: Saída arquivo base chamada construtor ajuda HTML . Padrão é 'pydoc'.

htmlhelp_file_suffix¶: Este é o sufixo do nome do arquivo para arquivos de ajuda HTML gerados. O padrão é ".html".

Novo na versão 2.0.

htmlhelp_link_suffix¶: Sufixo para links gerados para arquivos HTML. O padrão é ".html".

Novo na versão 2.0.

Opções para saída Ajuda Apple¶

Novo na versão 1.3.

Essas opções influenciam saída Ajuda Apple. Esse construtor deriva do construtor HTML, portanto opções também se aplicam onde apropriadas.

Nota

Saída Ajuda Apple só funciona no Mac OS X 10.6 e posterior, como requer hiutil e codesign na linha de comando, ambos não são Open Source.

Pode desabilitar essa funcionalidade usando applehelp_disable_external_tools, mas o resultado só será válido quando o indexador for executado nas pastas .lproj.

applehelp_bundle_name¶: Nome base para Apple Help Book. Padrão para nome projeto project.

applehelp_bundle_id¶: O ID do Conjunto para livro de ajuda itens.

Aviso

Esse valor deve ser configurado para gerar Ajuda Apple.

applehelp_dev_region¶: O região padrão desenv. Padrão para 'en-us', que é a recomentdação Apple.

applehelp_bundle_version¶: Versão do Conjunto (como string). Padrão para '1'.

applehelp_icon¶: O arquivo de ícone do pacote de ajuda ou None para nenhum ícone. De acordo com a documentação da Apple, esta deve ser uma versão de 16x16 pixels do ícone do aplicativo com um fundo transparente, salvo como um arquivo PNG.

applehelp_kb_product¶: Etiqueta produto usado applehelp_kb_url. Padrão para '<project>-<release>'.

applehelp_kb_url¶

O URL de seu servidor de base de conhecimento, por exemplo, https://example.com/kbsearch.py?p='product'&q='query'&l='lang'. O Visualizador de Ajuda irá substituir os valores 'product', 'query' e 'lang' em tempo de execução pelo conteúdo de applehelp_kb_product, o texto inserido pelo usuário no caixa de pesquisa e o idioma do sistema do usuário, respectivamente.

Padrão para None para pesquisa remota.

applehelp_remote_url¶

O URL para conteúdo remoto. Você pode colocar uma cópia da pasta Resources de seu Livro de Ajuda neste local e o Visualizador de Ajuda tentará usá-la para buscar conteúdo atualizado.

ex.. se configurar https://example.com/help/Foo/ e Visualizador Help utiliza uma cópia de index.html para idioma Inglês, irá parecer com https://example.com/help/Foo/en.lproj/index.html.

Padrão None para nenhum conteúdo remoto.

applehelp_index_anchors¶: Se True, informa ao indexador help para ancorar índices gerados em HTML. Pode ser útil na hora de navegar para um tópico em particular usando função AHLookupAnchor openHelpAnchor:inBook: em seu código. Também possibilita uso de URLs help:anchor; ver documentação Apple para maiores informações sobre esse tópico.

applehelp_min_term_length¶: Controla o tamanho mínimo para indexador help. Padrão para None, o que significa que o padrão será usado.

applehelp_stopwords¶

Especificação do idioma (usado para palavras-chave), ou o caminho para plist de palavras-chave ou None caso não desejar palavras-chave. A plist padrão de palavras-chave pode ser encontrada em /usr/share/hiutil/Stopwords.plist e contém, em tempo de geração, stopwords para os idiomas:

Idioma	Código
Inglês	en
Alemão	de
Espanhol	es
Francês	fr
Sueco	sv
Húngaro	hu
Italian	it

Defaults to language, or if that is not set, to 'en'.

applehelp_locale¶

Especifíca para qual locale será gerado o Help. Isso é usado para determinar o nome da pasta .lproj dento do Help Resources, e é passado ao indexador de ajuda.

Defaults to language, or if that is not set, to 'en'.

applehelp_title¶: Especifica o título do livro de jelp. Padrão para '<project> Help'.

applehelp_codesign_identity¶

Especifica a identidade do código de assinatura do usuário ou None se a assinatura não deve ser efetuada.

Padrão para o valor da variável de ambiente CODE_SIGN_IDENTITY, na qual Xcode constrói as fases, ou None se a variável não deve ser configurada.

applehelp_codesign_flags¶

Uma lista argumentos adicionais para passar ao codesign quando assinando o livro de help.

Padrão para lista baseada nos valores das variáveis do ambiente OTHER_CODE_SIGN_FLAGS, as quais pode ser usadas na construção pelo Xcode ou lista vazia se a variável não for configurada.

applehelp_indexer_path¶: O caminho para o programa hiutil. Padrão para '/usr/bin/hiutil'.

applehelp_codesign_path¶: O caminho para o programa codesign. Padrão '/usr/bin/codesign'.

applehelp_disable_external_tools¶

Se True, o construtor não irá executar o indexador ou a ferramente de assinatura, não importa o que outras configurações especificam.

Essa é a parte mais útil para teste, onde pode ser solicitado para o Sphinx ser construído em uma plataforma não MAC OS X e então completar apenas os passos finais no OS X.

O padrão é False.

Opções para saída epub¶

Essas opções influenciam a saída do epub. Como esse construtor deriva do construtor HTML, as opções HTML também se aplicam quando apropriado. Os valores reais para algumas das opções não são realmente importantes, eles apenas têm que ser inseridos nos metadados Dublin Core.

epub_basename¶: Nome do arquivo epub. O padrão é o nome project.

epub_theme¶: O tema HTML para saída epub. Desde que temas padrões não são otimizados para dispositivos telas menores, usando os mesmos temas HTML a saída epub não será adequada. Valor padrão para tema 'epub', é um tema para economizar espaço.

epub_theme_options¶: Dicionário de opções que influenciam aparência e comportamento do tema selecionado. São específicos para tema. Para opções inteligíveis dos temas veja this section.

Novo na versão 1.2.

epub_title¶: O título do documento. O padrão é a opção html_title, mas pode ser definido independentemente para a criação do epub. O padrão é a opção project.

Alterado na versão 2.0: Usa como padrão a opção project.

epub_description¶: A descrição do documento. O padrão é 'unknown'.

Novo na versão 1.4.

Alterado na versão 1.5: Renomeado a partir de epub3_description

epub_author¶: O autor do documento. Isso é gravado em metadados Dublin Core. Padrão opção author.

epub_contributor¶: O nome da pessoa, organização, etc. que desempenha papel secundário na criação de conteúdo na publicação EPUB. O padrão é 'desconhecido'.

Novo na versão 1.4.

Alterado na versão 1.5: Renomeado a partir de epub3_contributor

epub_language¶: O idioma do documento. Isso será gravado nos metadados Dublin Core. O padrão é opção confval:language ou 'en' se não for configurado.

epub_publisher¶: O editor do documento. Isso é colocado nos metadados Dublin Core. Você pode usar qualquer string sensível, por exemplo, a página inicial do projeto. O padrão é a opção author.

epub_copyright¶: Copyright do documento. Padrão para valor da opção copyright mas pode ser independentemente configurada para criação epub.

epub_identifier¶: Identificador para o documento. Isso é gravado nos metadados Dublin Core. Para publicação documentos é o número ISBN, mas pode ser usado um schema alternativo, ex.. nome página do projeto. O padrão é 'unknown'.

epub_scheme¶: Esquema para epub_identifier. Gravado nos metadados do Dublin Core. Para editores o esquema é 'ISBN'. Se usar página web, 'URL' pode atender. O valor padrão é 'unknown'.

epub_uid¶: Um identificador exclusivo para o documento. Isso é colocado nos metadados Dublin Core. Você pode usar uma string de formato de Name do XML. Você não pode usar hífen, ponto, números como um primeiro caractere. O valor padrão é 'unknown'.

epub_cover¶

Informação página abertura. Esse par contendo nome de arquivo da imagem do modelo html. A renderização da página será inserida como primeiro item do content.opf. Se o nome do modelo estiver vazio, nenhuma página abertura será criada. Nada será criado se o par estiver vazio. Exemplos:

epub_cover = ('_static/cover.png', 'epub-cover.html')
epub_cover = ('_static/cover.png', '')
epub_cover = ()

O valor padrão é ().

Novo na versão 1.1.

epub_css_files¶: Uma lista de arquivos CSS. A entrada deve ser uma string filename ou uma tupla contendo a string filename e o dicionário de attributes. Para mais informações, veja html_css_files.

Novo na versão 1.8.

epub_guide¶

Dados Meta para elementos guia do arquivo content.opf. Essa é a sequência de pares contendo type, e uri e o title da informação opcional de guia. Ver documentação OPF em http://idpf.org/epub para mais detalhes. Se possível, entradas padrões para tipos cover e toc são automaticamente inseridas. Contudo os tipos podem ser explicitamente sobrepostos se as entradas forem inapropriadas. Exemplo:

epub_guide = (('cover', 'cover.html', 'Cover Page'),)

O valor padrão é ().

epub_pre_files¶

Arquivo adicional deve ser inserido antes do texto gerado pelo Sphinx. Lista de pares contendo nome de arquivo e título. Se título está vazio, nenhuma entrada é adicionada para o arquivo toc.ncx. Exemplo:

epub_pre_files = [
    ('index.html', 'Welcome'),
]

O valor padrão é [].

epub_post_files¶: Arquivos adicionais que devem ser inseridos após o texto gerado pelo Sphinx. Lista de pares contendo nome do arquivo e título. Essa opção é usada para adicionar sufixo. Se o título está vazio, nenhuma entrada é adicionada para o arquivo toc.ncx. O padrão é [].

epub_exclude_files¶: Lista de arquivos que são gerados/copiados no diretório de construção mas não devem ser incluídos no arquivo epub. O padrão é [].

epub_tocdepth¶: A profundidade da tabela de conteúdos do arquivo toc.ncs. Deve ser um inteiro maior que zero. O padrão é 3. Nota: Estruturas mais abrangentes de tabela de conteúdos pode ser difícil para navegar.

epub_tocdup¶: Esse indicador determina se a entrada toc será inserida novamente no início da toc subordinada. Isso permite navegação mais fácil no topo do capítulo, mas pode ser confuso por misturar diversos níveis de hierárquia na lista. O padrão do valor é True.

epub_tocscope¶

Controla o escopo da tabela de conteúdos para epub. A configuração pode ter os seguintes valores:

'default' – inclui todas entradas toc não omitidas (padrão)
'includehidden' – inclui todas entras toc

Novo na versão 1.2.

epub_fix_images¶: Este sinalizador determina se o sphinx deve tentar corrigir formatos de imagem que não são suportados por alguns leitores epub. No momento, as imagens da paleta com uma pequena tabela de cores são atualizadas. Você precisa de Pillow, a Python Image Library, instalada para usar esta opção. O valor padrão é False porque a conversão automática pode perder informações.

Novo na versão 1.2.

epub_max_image_width¶: Essa opção especifíca largura máxima para imagens. Se valor for maior que zero, images com largura maior que o valor informado serão convertidas. Se valor for zero, nenhuma conversão será executada. valor padrão é 0. Python Image Library (Pillow) deve estar disponível para usar essa opção.

Novo na versão 1.2.

epub_show_urls¶

Controle exibição endereços URL. Útil para leitores que não possuem outras maneiras de exibir URL ligadas. A configuração pode ter os seguintes valores:

'inline' – exibir URLs dentro de parênteses (padrão)
'footnote' – exibir urls nas notas de rodapé.
'no' – não exibir URLs

Para exibir URLs vinculadas utilizar adição de regras CSS para classe link-target.

Novo na versão 1.2.

epub_use_index¶: Se verdadeiro, adiciona índice documento epub. Padrão para usar html_use_index opção pode ser configurada independentemente para criação epub.

Novo na versão 1.2.

epub_writing_mode¶

Especifica a direção da escrita. Pode ser 'horizontal' (padrão) ou 'vertical'

`epub_writing_mode`	`'horizontal'`	`'vertical'`
writing-mode [2]	`horizontal-tb`	`vertical-rl`
progressão página	esquerda para direita	direita para esquerda
Suporte Rolagem do Tema iBook’s	scroll-axis é vertical.	scroll-axis é horizontal.

Opções para saída LaTeX¶

Essas opções influenciam a saída do LaTeX.

latex_engine¶

O mecanismo LaTeX para construir documentos. A configuração pode ter os valores:

'pdflatex' – PDFLaTeX (padrão)
'xelatex' – XeLaTeX
'lualatex' – LuaLaTeX
'platex' – pLaTeX
'uplatex' – upLaTeX (padrão se language for 'ja')

Suporte do 'pdflatex' para caracteres Unicode é limitado.

Nota

2.0 adiciona suporte a 'pdflatex' em documentos de língua latina de letras ou palavras cirílicas ou gregas ocasionais. Isto não é automático, veja a discussão sobre a chave 'fontenc' de latex_elements.

Se o seu projeto usa caracteres Unicode, definir o mecanismo para 'xelatex' ou 'lualatex' e certificar-se de usar uma fonte OpenType com ampla cobertura de glifos é frequentemente mais fácil do que tentar fazer 'pdflatex' funcionar com os caracteres Unicode extras. Desde o Sphinx 2.0, o padrão é o GNU FreeFont que cobre bem o latim, cirílico e grego.

Alterado na versão 2.1.0: Usa xelatex (e o pacote LaTeX xeCJK) por padrão para documentos chineses.

Alterado na versão 2.2.1: Usa xelatex por padrão para documentos gregos.

Alterado na versão 2.3: Adiciona suporte a uplatex.

Alterado na versão 4.0: uplatex se torna a configuração padrão de documentos japoneses.

Ao contrário da renderização matemática de MathJaX na saída HTML, o LaTeX requer alguma configuração extra para oferecer suporte a literais Unicode em math: a única solução abrangente (até onde sabemos) é usar 'xelatex' ou 'lualatex' e para adicionar r'\usepackage{unicode-math}' (por exemplo, através da chave 'preamble' de latex_elements) Você pode preferir r'\usepackage[math-style=literal]{unicode-math}' para manter um Unicode literal como α (U+03B1) por exemplo como está na saída, em vez de sendo renderizado como $\alpha$.

latex_documents¶

Este valor determina como agrupar a árvore de documentos em arquivos fonte LaTeX. Deve ser uma lista de tuplas (startdocname, targetname, title, author, theme, toctree_only), onde os itens são:

startdocname: String que especifica o nome do documento do documento mestre do arquivo LaTeX. Todos os documentos referenciados pelo documento startdoc nas árvores TOC serão incluídos no arquivo LaTeX. (Se você deseja usar o documento raiz padrão para sua construção LaTeX, forneça seu root_doc aqui.)
targetname: Nome de arquivo do arquivo LaTeX no diretório de saída.
title: Título do documento LaTeX. Pode estar vazio para usar o título do documento startdoc. Isso é inserido como marcação LaTeX, portanto, caracteres especiais como uma barra invertida ou “e” comercial devem ser representados pelos comandos LaTeX apropriados se forem inseridos literalmente.
author: Autor do documento LaTeX. A mesma advertência de marcação LaTeX que para title se aplica. Use \\and para separar vários autores, como em: 'John \\and Sarah' (as barras invertidas devem ter escape do Python para chegar ao LaTeX).
theme: Tema LaTeX. Veja latex_theme.
toctree_only: Deve ser True ou False. Se verdadeiro, o próprio documento startdoc não é incluído na saída, apenas os documentos referenciados por ele por meio de árvores TOC. Com esta opção, você pode colocar coisas extras no documento mestre que aparecem no HTML, mas não na saída LaTeX.

Novo na versão 1.2: Anteriormente incluindo classe do seu próprio documento podia ser prefixado a nome da classe com a string “sphinx”. Não é mais necessário.

Novo na versão 0.3: O sexto item de toctree_only. Pares com 5 itens são aceitos.

latex_logo¶: Se informado deve ser o nome de um arquivo de imagem (relativo ao diretório de configuração) que será o logo dos docs. Será colocado no topo do título da página. Padrão None.

latex_toplevel_sectioning¶

Este valor determina a unidade de corte superior. Deve ser escolhido entre 'part', 'chapter' ou 'section'. O padrão é None; a unidade de seção mais alta é trocada por documentclass: section é usado se documentclass for howto, caso contrário, chapter será usado.

Observe que se o LaTeX usa o comando \part, então a numeração das unidades de seção em um nível de profundidade fica fora de sincronia com a numeração HTML, porque os números LaTeX continuamente \chapter (ou \section para howto.)

Novo na versão 1.4.

latex_appendices¶: Lista de nomes de documentos que serão anexados para todos manuais.

latex_domain_indices¶

Se verdadeiro, gera índices específicos do domínio em adição ao índice geral. Por ex. domínio Python, é um módulo índice global. Padrão é Verdadeiro.

Esse valor pode ser booleano ou lista de nomes de índices que devem ser gerados, para html_domain_indices.

Novo na versão 1.0.

latex_show_pagerefs¶: Se verdadeiro, adiciona página após referências internas. Isso é útil para cópias impressas do manual. Padrão é False.

Novo na versão 1.0.

latex_show_urls¶

Controle exibição endereços URL. É util para imprimir copias do manual. A configuração deve ter os seguintes valores:

'no' – não exibir URLs (padrão)
'footnote' – exibir urls nas notas de rodapé.
'inline' – exibir URLs inline em parenteses

Novo na versão 1.0.

Alterado na versão 1.1: O valor é uma string; anteriormente era um valor boleano e valor verdadeiro selecionado exibir 'inline'. Por compatibilidade anterior, True ainda é aceito.

latex_use_latex_multicolumn¶

O padrão é False: significa que as próprias macros do Sphinx são usadas para células mescladas de tabelas de grade. Eles permitem conteúdos gerais (blocos literais, listas, blocos de citação, …) mas podem ter problemas se a diretiva tabularcolumns foi usada para injetar marcação LaTeX do tipo >{..}, <{..}, @{..} como especificação de coluna.

Definir como True significa usar o padrão do LaTeX \multicolumn; isso é incompatível com blocos literais na célula mesclada horizontalmente e também com vários parágrafos em tal célula se a tabela for renderizada usando tabulary.

Novo na versão 1.6.

latex_table_style¶

A list of styling classes (strings). Currently supported:

'booktabs': no vertical lines, and only 2 or 3 horizontal lines (the latter if there is a header), using the booktabs package.
'borderless': no lines whatsoever.
'colorrows': the table rows are rendered with alternating background colours. The interface to customize them is via dedicated keys of The sphinxsetup configuration setting.

Importante

With the 'colorrows' style, the \rowcolors LaTeX command becomes a no-op (this command has limitations and has never correctly supported all types of tables Sphinx produces in LaTeX). Please update your project to use instead the latex table color configuration keys.

Default: ['booktabs', 'colorrows']

Novo na versão 5.3.0.

Alterado na versão 6.0.0: Modify default from [] to ['booktabs', 'colorrows'].

Each table can override the global style via :class: option, or .. rst-class:: for no-directive tables (cf. Tabelas). Currently recognized classes are booktabs, borderless, standard, colorrows, nocolorrows. The latter two can be combined with any of the first three. The standard class produces tables with both horizontal and vertical lines (as has been the default so far with Sphinx).

A single-row multi-column merged cell will obey the row colour, if it is set. See also TableMergeColor{Header,Odd,Even} in the The sphinxsetup configuration setting section.

Nota

It is hard-coded in LaTeX that a single cell will obey the row colour even if there is a column colour set via \columncolor from a column specification (see tabularcolumns). Sphinx provides \sphinxnorowcolor which can be used like this:
```
>{\columncolor{blue}\sphinxnorowcolor}
```
in a table column specification.
Sphinx also provides \sphinxcolorblend which however requires the xcolor package. Here is an example:
```
>{\sphinxcolorblend{!95!red}}
```
It means that in this column, the row colours will be slightly tinted by red; refer to xcolor documentation for more on the syntax of its \blendcolors command (a \blendcolors in place of \sphinxcolorblend would modify colours of the cell contents, not of the cell background colour panel…). You can find an example of usage in the APIs em Desuso section of this document in PDF format.

Dica

If you want to use a special colour for the contents of the cells of a given column use >{\noindent\color{<color>}}, possibly in addition to the above.
Multi-row merged cells, whether single column or multi-column currently ignore any set column, row, or cell colour.
It is possible for a simple cell to set a custom colour via the raw directive and the \cellcolor LaTeX command used anywhere in the cell contents. This currently is without effect in a merged cell, whatever its kind.

Dica

In a document not using 'booktabs' globally, it is possible to style an individual table via the booktabs class, but it will be necessary to add r'\usepackage{booktabs}' to the LaTeX preamble.

On the other hand one can use colorrows class for individual tables with no extra package (as Sphinx since 5.3.0 always loads colortbl).

latex_use_xindy¶

Se for True, o PDF compilado a partir dos arquivos LaTeX criados pelo Sphinx usará xindy (doc__) em vez de makeindex para preparar o índice de termos gerais (do uso de index). Isso significa que palavras com caracteres UTF-8 serão ordenadas corretamente para language.

Esta opção é ignorada se latex_engine for 'platex' (documentos japoneses; mendex substitui makeindex).
O padrão é True para 'xelatex' ou 'lualatex' como makeindex, se qualquer termo indexado começar com um caractere não ascii, cria arquivos .ind contendo bytes inválidos para codificação UTF-8. Com 'lualatex' isso então quebra a compilação do PDF.
O padrão é False para 'pdflatex' mas True é recomendado para documentos que não estejam em inglês assim que alguns termos indexados usem caracteres não ascii do script de idioma.

Sphinx adiciona à distribuição de base xindy algum suporte dedicado para usar o mecanismo 'pdflatex' com scripts cirílicos. E seja com motores 'pdflatex' ou Unicode, os documentos cirílicos lidam corretamente com a indexação de nomes latinos, mesmo com sinais diacríticos.

Novo na versão 1.8.

latex_elements¶: Novo na versão 0.5.

Sua documentação foi movida para Configuração LaTeX.

latex_docclass¶: Dicionário mapeando 'howto' e 'manual' para nomes reais de documentos e classes que serão usadas como classes Sphinx. Padrão é usar 'article' para 'howto' e 'report' para 'manual'.

Novo na versão 1.0.

Alterado na versão 1.5: Em documentos japoneses (language é 'ja'), por padrão 'jreport' é usado para 'howto' e 'jsbook' para 'manual'.

latex_additional_files¶

Lista de nome de arquivos, relativos ao diretório de configuração, para serem copiados para o diretório de construção quando gerando saída LaTeX. Isso é útil para copiar arquivos Sphinx que não são copiados automaticamente, ex: quando são referenciados por LaTeX configurável adicionados em latex_elements. Arquivos de Imagem que são referenciados na fonte (ex: via .. image::) são copiados automaticamente.

Confirmar que o nome de arquivo não conflita com nenhum arquivo que é copiado automaticamente.

Atenção

Filenames with extension .tex will automatically be handed over to the PDF build process triggered by sphinx-build -M latexpdf or by make latexpdf. If the file was added only to be \input{} from a modified preamble, you must add a further suffix such as .txt to the filename and adjust accordingly the \input{} command added to the LaTeX document preamble.

Novo na versão 0.6.

Alterado na versão 1.2: Isso sobrescreve os arquivos fornecidos pelo Sphinx, como sphinx.sty.

latex_theme¶

O “tema” que a saída LaTeX deve usar. É uma coleção de configurações para a saída LaTeX (por exemplo, classe de documento, unidade de corte de nível superior e assim por diante).

Como um tema LaTeX embutido, manual e howto são empacotados.

manual: Um tema LaTeX para escrever um manual. Ele importa a classe de documento report (documentos japoneses usam jsbook).
howto: Um tema LaTeX para escrever um artigo. Ele importa a classe de documento article (documentos japoneses usam jreport). latex_appendices está disponível apenas para este tema.

Seu padrão é 'manual'.

Novo na versão 3.0.

latex_theme_options¶: Um dicionário de opções que influenciam a aparência do tema selecionado.

Novo na versão 3.1.

latex_theme_path¶: Uma lista de caminhos que contêm temas LaTeX personalizados como subdiretórios. Os caminhos relativos são considerados relativos ao diretório de configuração.

Novo na versão 3.0.

Opções para saída texto¶

Essas opções influenciam a saída texto.

text_newlines¶

Determina caracter usado como final de linha na saída texto.

'unix': Usa estilo para finalizar linhas (\n)
'windows': Usa o estilo Windows para finalizar linhas (\r\n)
'native': Usa o estilo de fim de linha da plataforma onde está sendo construída a documentação.

Padrão: 'unix'.

Novo na versão 1.1.

text_sectionchars¶

String de 7 caracteres que deve ser usada para seções contidas. O primeiro caracter é usado para cabeçalhos do primeiro nível, segundo caracter para segundo nível e assim sucessivamente.

Padrão é '*=-~"+`'.

Novo na versão 1.1.

text_add_secnumbers¶: Booleano que decide quando os números de seção são incluídos na saída do texto. Padrão é True.

Novo na versão 1.7.

text_secnumber_suffix¶: Sufixo para números de seção na saída de texto. Padrão: ".". Defina como "" para suprimir o ponto final nos números de seção.

Novo na versão 1.7.

Opções para saída página manual¶

Essas opções influenciam a saída página manual.

man_pages¶

Esse valor determina como o grupo de páginas aparecem no manual. Deve ser uma lista de pares (startdocname, name, description, authors, section), onde os itens são:

startdocname: String que especifica o nome do documento do documento mestre da página de manual. Todos os documentos referenciados pelo documento startdoc nas árvores TOC serão incluídos no arquivo de manual. (Se você deseja usar o documento raiz padrão para sua construção de páginas de manual, use seu root_doc aqui.)
name: Nome da página de manual. Deve ser uma string curta sem espaços ou caracteres especiais. É usado para determinar o nome do arquivo, bem como o nome da página do manual (na seção NAME).
description: Descrição da página de manual. Isso é usado na seção NAME. Pode ser uma string vazia se você não quiser gerar automaticamente a seção NAME.
authors: Uma lista de strings com autores ou uma única string. Pode ser uma string ou lista vazia se você não quiser gerar automaticamente uma seção AUTHORS na página de manual.
section: A seção da página de manual. Usado para o nome do arquivo de saída, bem como no cabeçalho da página de manual.

Novo na versão 1.0.

man_show_urls¶: Se Verdadeiro, adiciona endereços URL após links. Padrão False.

Novo na versão 1.1.

man_make_section_directory¶: Se verdadeiro, cria um diretório de seção na página de manual de construção. O padrão é True.

Novo na versão 3.3.

Alterado na versão 4.0: O padrão foi alterado para False de True.

Alterado na versão 4.0.2: O padrão foi alterado para True para False novamente.

Opções para saida TexInfo¶

Essas opções influenciam a saida Texinfo.

texinfo_documents¶

Esse valor determina como a raiz do grupo de documento em arquivos fontes Texinfo. Devem ser uma lista de pares (startdocname, targetname, title, author, dir_entry, description, category, toctree_only) onde itens são:

startdocname: String que especifica o nome do documento do documento mestre do arquivo Texinfo. Todos os documentos referenciados pelo documento startdoc nas árvores TOC serão incluídos no arquivo Texinfo. (Se você deseja usar o documento mestre padrão para sua construção Texinfo, forneça seu root_doc aqui.)
targetname: Nome de arquivo (sem extensão) do arquivo Texinfo no diretório de saída.
title: Título do documento Texinfo. Pode estar vazio para usar o título do documento startdoc. Inserido como marcação Texinfo, portanto, caracteres especiais como ``@ `` e ``{} `` precisarão ser escapados para serem inseridos literalmente.
author: Autor do documento Texinfo. Inserido como marcação Texinfo. Use @* para separar vários autores, como em: 'John@*Sarah'.
dir_entry: O nome que vai aparecer no arquivo de menu de topo de nível DIR.
description: Um texto descritivo que vai aparecer no arquivo de menu de topo de nível DIR.
category: Especifica a seção na qual esta entrada vai aparecer no arquivo de menu de topo de nível DIR.
toctree_only: Deve ser True ou False. Se verdadeiro, o próprio documento startdoc não é incluído na saída, apenas os documentos referenciados por ele por meio de árvores TOC. Com esta opção, você pode colocar coisas extras no documento mestre que aparecem no HTML, mas não na saída do Texinfo.

Novo na versão 1.1.

texinfo_appendices¶: Lista de nomes de documentos que serão anexados para todos manuais.

Novo na versão 1.1.

texinfo_domain_indices¶

Se verdadeiro, gera índices específicos do domínio em adição ao índice geral. Por ex. domínio Python, é um módulo índice global. Padrão é Verdadeiro.

Esse valor pode ser booleano ou lista de nomes de índices que devem ser gerados, para html_domain_indices.

Novo na versão 1.1.

texinfo_show_urls¶

Controlear como exibir endereços URL.

'footnote' – Exibir URLs nas notas de rodapé.
'no' – não exibir URLs
'inline' – exibir URLs inline em parenteses

Novo na versão 1.1.

texinfo_no_detailmenu¶: Se verdadeiro, não gerar @detailmenu no “Topo” do menu contendo entradas para cada sub-menu do documento. O padrão é False.

Novo na versão 1.2.

texinfo_elements¶

Um dicionário que contém TexInfo que sobrepõe aqueles que o Sphinx usualmente coloca nos arquivos gerados .texi.

Chaves que podem ser sobrepostas são:

'paragraphindent'
Número de espaços para indentar a primeira linha de cada parágrafo, padrão 2. Especificar 0 para não haver indentação.

'exampleindent'
Número de espaços para indentar as linhas de exemplo ou blocos de literais, padrão 4. Especificar 0 para não haver indentação.

'preamble'
Marcação TexInfo inserida próxima do início do arquivo.

'copying'
Marcações inseridas com o bloco
Chaves que configuram outras opções e podem ser sobrepostas são:

'author' 'body' 'date' 'direntry' 'filename' 'project' 'release' 'title'

Novo na versão 1.1.

texinfo_cross_references¶: Se false, não gera referências embutidas em um documento. Isso torna um arquivo de informação mais legível com o leitor autônomo (info). O padrão é True.

Novo na versão 4.4.

Opções para saída QtHelp¶

Essas opções influenciam a saída do qthelp. Como esse construtor deriva do construtor HTML, as opções HTML também se aplicam quando apropriado.

qthelp_basename¶: O nome base do arquivo qthelp. O padrão é o nome projeto.

qthelp_namespace¶: O namespace para o arquivo qthelp. O padrão é org.sphinx.<project_name>.<project_version>.

qthelp_theme¶: Tema HTML para saída qthelp. Padrão 'nonav'.

qthelp_theme_options¶: Dicionário de opções que influenciam aparência e comportamento do tema selecionado. São específicos para tema. Para opções inteligíveis dos temas veja this section.

Opções para construtor linkcheck¶

linkcheck_ignore¶

A lista de expressões regulares que combinam com as URIs que não precisam ser verificadas com o construtor linkcheck`. Exemplo:

linkcheck_ignore = [r'http://localhost:\d+/']

Novo na versão 1.1.

linkcheck_allowed_redirects¶

Um dicionário que mapeia um padrão do URI de origem para um padrão do URI canônico. O construtor linkcheck trata o link redirecionado como “funcionando” quando:

o link no documento corresponde ao padrão de URI de origem e
o local de redirecionamento corresponde ao padrão de URI canônico.

Exemplo:

linkcheck_allowed_redirects = {
    # All HTTP redirections from the source URI to the canonical URI will be treated as "working".
    r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*'
}

Se definido, o construtor linkcheck emitirá um aviso quando o redirecionamento não permitido for encontrado. É útil para detectar redirecionamentos inesperados em o modo warn-is-error.

Novo na versão 4.1.

linkcheck_request_headers¶

Um dicionário que mapeia baseurls para cabeçalhos de solicitação HTTP.

A chave é uma string base de URL como "https://www.sphinx-doc.org/". Para especificar cabeçalhos para outros hosts, "*" pode ser usado. Ele corresponde a todos os hosts somente quando o URL não corresponde a outras configurações.

O valor é um dicionário que mapeia nome de cabeçalho para seu valor.

Exemplo:

linkcheck_request_headers = {
    "https://www.sphinx-doc.org/": {
        "Accept": "text/html",
        "Accept-Encoding": "utf-8",
    },
    "*": {
        "Accept": "text/html,application/xhtml+xml",
    }
}

Novo na versão 3.1.

linkcheck_retries¶: O número de vezes que o construtor linkcheck irá tentar verificar a URL antes de assumir que está quebrada. Padrão 1 tentativa.

Novo na versão 1.4.

linkcheck_timeout¶: Tempo para timeout, em segundos, para o construtor de verificação de links. O padrão é usar o tempo padrão do soquete Python.

Novo na versão 1.1.

linkcheck_workers¶: O número de threads concomitantes para usar quando verificando links. Padrão 5 threads.

Novo na versão 1.1.

linkcheck_anchors¶: Se verdadeiro, o validador do link #anchor. Isso requer download do documento por inteiro e é consideravelmente mais lento quando habilitado. Padrão é Verdadeiro.

Novo na versão 1.2.

linkcheck_anchors_ignore¶

Uma lista de expressões regulares que correspondem às âncoras Sphinx deve pular ao verificar a validade das âncoras nos links. Isso permite pular âncoras que o JavaScript de um site adiciona para controlar páginas dinâmicas ou ao acionar uma solicitação REST interna. O padrão é ["^!"].

Dica

Use linkcheck_anchors_ignore_for_url to check a URL, but skip verifying that the anchors exist.

Nota

Se você quiser ignorar as âncoras de uma página específica ou de páginas que correspondem a um padrão específico (mas ainda verificar ocorrências das mesmas páginas que não têm âncoras), use linkcheck_ignore em vez disso, por exemplo como segue:

linkcheck_ignore = [
   'https://www.sphinx-doc.org/en/1.7/intro.html#',
]

Novo na versão 1.5.

linkcheck_anchors_ignore_for_url¶: A list or tuple of regular expressions matching URLs for which Sphinx should not check the validity of anchors. This allows skipping anchor checks on a per-page basis while still checking the validity of the page itself. Default is an empty tuple ().

Novo na versão 7.1.

linkcheck_auth¶

Passa informações de autenticação ao fazer uma construção linkcheck.

Uma lista de tuplas (regex_pattern, auth_info) nas quais os itens são:

regex_pattern: Uma expressão regular que corresponde a uma URI.
auth_info: Informações de autenticação a serem usadas para esse URI. O valor pode ser qualquer coisa que seja compreendida pela biblioteca requests (veja Authentication do requests para detalhes).

O construtor linkcheck usará o primeiro valor auth_info correspondente que puder encontrar na lista linkcheck_auth, então os valores anteriores na lista têm maior prioridade.

Exemplo:

linkcheck_auth = [
  ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')),
  ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)),
]

Novo na versão 2.3.

linkcheck_rate_limit_timeout¶

O construtor linkcheck pode emitir um grande número de solicitações para o mesmo site em um curto período de tempo. Esta configuração controla o comportamento do construtor quando os servidores indicam que os pedidos são limitados por taxa.

Se um servidor indica quando tentar novamente (usando o cabeçalho Retry-After), linkcheck sempre segue a indicação do servidor.

Caso contrário, linkcheck espera um minuto antes de tentar novamente e continua dobrando o tempo de espera entre as tentativas até que tenha sucesso ou exceda o linkcheck_rate_limit_timeout. Por padrão, o tempo limite é de 5 minutos.

Novo na versão 3.4.

linkcheck_exclude_documents¶

Uma lista de expressões regulares que correspondem a documentos nos quais o Sphinx não deve verificar a validade dos links. Isso pode ser usado para permitir o enfraquecimento do link em seções herdadas ou históricas da documentação.

Exemplo:

# ignore all links in documents located in a subfolder named 'legacy'
linkcheck_exclude_documents = [r'.*/legacy/.*']

Novo na versão 4.4.

Opções para construtor XML¶

xml_pretty¶: Se verdadeiro, impressão formatada de XML. Padrão é Verdadeiro.

Novo na versão 1.2.

Notas de Rodapé

Opções para o domínio C¶

c_id_attributes¶: Lista de termos que podem ser aceitos como atributos. Isso pode por exemplo ser usado como atributos #define são usados para portabilidade.

Novo na versão 3.0.

c_paren_attributes¶: Uma lista de strings que o analisador também deve aceitar como atributos com um argumento. Ou seja, se my_align_as estiver na lista, então my_align_as(X) é analisado como um atributo para todas as strings X que têm parênteses, colchetes e chaves balanceados (ou seja, (), [] e {}). Isso pode, por exemplo, ser usado quando os atributos foram definidos, com #define, para portabilidade.

Novo na versão 3.0.

c_extra_keywords¶: Uma lista de identificadores a serem reconhecidos como palavras-chave pelo analisador C. O padrão é ['alignas', 'alignof', 'bool', 'complex', 'imaginary', 'noreturn', 'static_assert', 'thread_local'].

Novo na versão 4.0.3.

c_maximum_signature_line_length¶: If a signature’s length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding maximum_signature_line_length.

Novo na versão 7.1.

Opções para domínio C++¶

cpp_index_common_prefix¶: Uma lista de prefixos que serão ignorados ao classificar objetos C++ no índice global. Por exemplo ['awesome_lib::'].

Novo na versão 1.5.

cpp_id_attributes¶: Lista de termos que podem ser aceitos como atributos. Isso pode por exemplo ser usado como atributos #define são usados para portabilidade.

Novo na versão 1.5.

cpp_paren_attributes¶: Uma lista de strings que o analisador também deve aceitar como atributos com um argumento. Ou seja, se my_align_as estiver na lista, então my_align_as(X) é analisado como um atributo para todas as strings X que têm parênteses, colchetes e chaves balanceados (ou seja, (), [] e {}). Isso pode, por exemplo, ser usado quando os atributos foram definidos, com #define, para portabilidade.

Novo na versão 1.5.

cpp_maximum_signature_line_length¶: If a signature’s length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding maximum_signature_line_length.

Novo na versão 7.1.

Opções para o domínio Python¶

python_display_short_literal_types¶

This value controls how Literal types are displayed. The setting is a boolean, default False.

Exemplos¶

The examples below use the following py:function directive:

.. py:function:: serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

When False, Literal types display as per standard Python syntax, i.e.:

serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

When True, Literal types display with a short, PEP 604-inspired syntax, i.e.:

serve_food(item: "egg" | "spam" | "lobster thermidor") -> None

Novo na versão 6.2.

python_use_unqualified_type_names¶: Se verdadeiro, suprime o nome do módulo da referência python se puder ser resolvido. O padrão é False.

Novo na versão 4.0.

Nota

Esta configuração ainda está em fase experimental

python_maximum_signature_line_length¶

If a signature’s length in characters exceeds the number set, each argument or type parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding maximum_signature_line_length.

For the Python domain, the signature length depends on whether the type parameters or the list of arguments are being formatted. For the former, the signature length ignores the length of the arguments list; for the latter, the signature length ignores the length of the type parameters list.

For instance, with python_maximum_signature_line_length = 20, only the list of type parameters will be wrapped while the arguments list will be rendered on a single line

.. py:function:: add[T: VERY_LONG_SUPER_TYPE, U: VERY_LONG_SUPER_TYPE](a: T, b: U)

Novo na versão 7.1.

Options for the Javascript domain¶

javascript_maximum_signature_line_length¶: If a signature’s length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding maximum_signature_line_length.

Novo na versão 7.1.

Exemplo de arquivo configuração¶

# test documentation build configuration file, created by
# sphinx-quickstart on Sun Jun 26 00:00:43 2016.
#
# This file is executed through importlib.import_module with 
# the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

# -- General configuration ------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'

# The encoding of source files.
#
# source_encoding = 'utf-8-sig'

# The master toctree document.
root_doc = 'index'

# General information about the project.
project = 'test'
copyright = '2016, test'
author = 'test'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = 'test'
# The full version, including alpha/beta/rc tags.
release = 'test'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#
# today = ''
#
# Else, today_fmt is used as the format for a strftime call.
#
# today_fmt = '%B %d, %Y'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# These patterns also affect html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# The reST default role (used for this markup: `text`) to use for all
# documents.
#
# default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.
#
# add_function_parentheses = True

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#
# add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#
# show_authors = False

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []

# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False


# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}

# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []

# The name for this set of Sphinx documents.
# "<project> v<release> documentation" by default.
#
# html_title = 'test vtest'

# A shorter title for the navigation bar.  Default is the same as html_title.
#
# html_short_title = None

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#
# html_logo = None

# The name of an image file (relative to this directory) to use as a favicon of
# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#
# html_favicon = None

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#
# html_extra_path = []

# If not None, a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
# The empty string is equivalent to '%b %d, %Y'.
#
# html_last_updated_fmt = None

# Custom sidebar templates, maps document names to template names.
#
# html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to
# template names.
#
# html_additional_pages = {}

# If false, no module index is generated.
#
# html_domain_indices = True

# If false, no index is generated.
#
# html_use_index = True

# If true, the index is split into individual pages for each letter.
#
# html_split_index = False

# If true, links to the reST sources are added to the pages.
#
# html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
# html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#
# html_show_copyright = True

# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it.  The value of this option must be the
# base URL from which the finished HTML is served.
#
# html_use_opensearch = ''

# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None

# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
#
# html_search_language = 'en'

# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change `jieba` dictionary path.
#
# html_search_options = {'type': 'default'}

# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#
# html_search_scorer = 'scorer.js'

# Output file base name for HTML help builder.
htmlhelp_basename = 'testdoc'

# -- Options for LaTeX output ---------------------------------------------

latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #
    # 'papersize': 'letterpaper',

    # The font size ('10pt', '11pt' or '12pt').
    #
    # 'pointsize': '10pt',

    # Additional stuff for the LaTeX preamble.
    #
    # 'preamble': '',

    # Latex figure (float) alignment
    #
    # 'figure_align': 'htbp',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
    (root_doc, 'test.tex', 'test Documentation',
     'test', 'manual'),
]

# The name of an image file (relative to this directory) to place at the top of
# the title page.
#
# latex_logo = None

# If true, show page references after internal links.
#
# latex_show_pagerefs = False

# If true, show URL addresses after external links.
#
# latex_show_urls = False

# Documents to append as an appendix to all manuals.
#
# latex_appendices = []

# If false, no module index is generated.
#
# latex_domain_indices = True


# -- Options for manual page output ---------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    (root_doc, 'test', 'test Documentation',
     [author], 1)
]

# If true, show URL addresses after external links.
#
# man_show_urls = False


# -- Options for Texinfo output -------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [
    (root_doc, 'test', 'test Documentation',
     author, 'test', 'One line description of project.',
     'Miscellaneous'),
]

# Documents to append as an appendix to all manuals.
#
# texinfo_appendices = []

# If false, no module index is generated.
#
# texinfo_domain_indices = True

# How to display URL addresses: 'footnote', 'no', or 'inline'.
#
# texinfo_show_urls = 'footnote'

# If true, do not generate a @detailmenu in the "Top" node's menu.
#
# texinfo_no_detailmenu = False

# If false, do not generate in manual @ref nodes.
#
# texinfo_cross_references = False

# -- A random example -----------------------------------------------------

import sys, os
sys.path.insert(0, os.path.abspath('.'))
exclude_patterns = ['zzz']

numfig = True
#language = 'ja'

extensions.append('sphinx.ext.todo')
extensions.append('sphinx.ext.autodoc')
#extensions.append('sphinx.ext.autosummary')
extensions.append('sphinx.ext.intersphinx')
extensions.append('sphinx.ext.mathjax')
extensions.append('sphinx.ext.viewcode')
extensions.append('sphinx.ext.graphviz')


autosummary_generate = True
html_theme = 'default'
#source_suffix = ['.rst', '.txt']

On this page

Site navigation

Configuração¶

Informação do Projeto¶

Configuração Geral¶

Opções para internacionalização¶

Opções para Math¶

Opções para saída HTML¶

Opções para a saída Single HTML¶

Opções para ajuda saída HTML¶

Opções para saída Ajuda Apple¶

Opções para saída epub¶

Opções para saída LaTeX¶

Opções para saída texto¶

Opções para saída página manual¶

Opções para saida TexInfo¶

Opções para saída QtHelp¶

Opções para construtor linkcheck¶

Opções para construtor XML¶

Opções para o domínio C¶

Opções para domínio C++¶

Opções para o domínio Python¶

Exemplos¶

Options for the Javascript domain¶

Exemplo de arquivo configuração¶