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.

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” (do inglês fully-qualified name - FQN) refere-se a uma string que nomeia um objeto Python importável dentro de um módulo; por exemplo:, o nome totalmente qualificado "sphinx.builders.Builder" quer dizer a classe Builder no módulo sphinx.builders.
Nomes dos documentos usam / como separador do caminho e não contêm o nome da extensão do arquivo.

One padrões estilo glob são permitidos, você pode usar as construções padrões do shell (*, ?, [...] e [!...]) com a funcionalidade que nenhuma dessas vai corresponder barras (/). Asterisco duplo ** pode ser usada para combinar com qualquer sequência de caracteres incluindo barras.

Dica

O arquivo de configuração é executado com código Python em tempo de construção (usando importlib.import_module(), com o diretório atual definido para o diretório de configuração) e suporta a execução arbitrária de códigos complexos.

O Sphinx então lê nomes simples do espaço de nomes do arquivo como sua configuração. Em geral, os valores de configuração devem ser sequências simples, números ou listas ou dicionários de valores simples.

O conteúdo do espaço de nomes 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 espaço de nomes com o comando del conforme apropriado. Módulos são removidos automaticamente, de forma que excluir módulos importados não é necessário.

Tags do projeto¶

Existe um objeto especial chamado tags disponível no arquivo de configuração, que expõe as tags do projeto. Tags são definidas através da opção de linha de comando --tag ou tags.add('tag'). Observe que o nome do construtor e as tags de formato não estão disponíveis em conf.py.

Pode ser usado para consultar e alterar as tags definidas da seguinte forma:

Para consultar se uma tag está definida, use 'tag' in tags.
Para adicionar uma tag, use tags.add('tag').
Para remover uma tag, use tags.remove('tag').

Informações do projeto¶

project¶

Tipo:: str
Padrão:: 'Project name not set'

O nome do projeto documento. Exemplo:

project = 'Thermidor'

author¶

Tipo:: str
Padrão:: 'Author name not set'

Os autores do projeto. Exemplo:

author = 'Joe Bloggs'

copyright¶

project_copyright¶

Tipo:: str | Sequence[str]
Padrão:: ''

Uma instrução de direitos autorais. Os estilos permitidos são os seguintes, onde ‘AAAA’ representa um ano de quatro dígitos.

copyright = 'AAAA'
copyright = 'AAAA, Nome do Autor'
copyright = 'AAAA Nome do Autor'
copyright = 'AAAA-AAAA, Nome do Autor'
copyright = 'AAAA-AAAA Nome do Autor'

Se a string '%Y' aparecer em uma linha de direitos autorais, ela será substituída pelo ano atual de quatro dígitos. Por exemplo:

copyright = '%Y'
copyright = '%Y, Nome do Autor'
copyright = 'YYYY-%Y, Nome do Autor'

Adicionado na versão 3.5: O apelido project_copyright.;

Alterado na versão 7.1: O valor agora pode ser uma sequência de declarações de direitos autorais no formato acima, que serão exibidas cada uma em sua própria linha.

Alterado na versão 8.1: As declarações de direitos autorais oferecem suporte ao espaço reservado '%Y'.

version¶

Tipo:: str
Padrão:: ''

A versão principal do projeto, usada como substituto para a substituição padrão |version|.

Isso pode ser algo como version = '4.2'. A versão completa do projeto é definida em release.

Se o seu projeto não fizer uma distinção significativa entre uma versão ‘completa’ e ‘principal’, defina version e release com o mesmo valor.

release¶

Tipo:: str
Padrão:: ''

A versão completa do projeto, usada como substituto para a substituição padrão |release| e, por exemplo, nos modelos HTML.

Isso pode ser algo como release = '4.2.1b0'. A versão principal (curta) do projeto é definida em version.

Se o seu projeto não fizer uma distinção significativa entre uma versão ‘completa’ e ‘principal’, defina version e release com o mesmo valor.

Configurações gerais¶

needs_sphinx¶

Tipo:: str
Padrão:: ''

Define uma versão mínima suportada do Sphinx necessária para construir o projeto. O formato deve ser uma string de versão 'major.minor' como '1.1' O Sphinx irá compará-lo com sua versão e se recusará a construir o projeto se a versão em execução do Sphinx for muito antiga. Por padrão, não há versão mínima.

Adicionado na versão 1.0.

Alterado na versão 1.4: Permite uma string de versão 'major.minor.micro'.

extensions¶

Tipo:: list[str]
Padrão:: []

Uma lista de strings que são nomes de módulos de extensões Sphinx. Essas podem ser extensões inclusas no Sphinx (chamadas sphinx.ext.*) e extensões de originais personalizadas ou de terceiros..

Para usar uma extensão de terceiros, você deve garantir que ela esteja instalada e incluí-la na lista extensions, assim:

extensions = [
    ...
    'numpydoc',
]

Existem duas opções para extensões originais. O próprio arquivo de configuração pode ser uma extensão; para isso, você só precisa fornecer uma função setup() nele. Caso contrário, você deverá garantir que sua extensão personalizada seja importável e esteja localizada em um diretório que esteja no caminho do Python.

Certifique-se de que caminhos absolutos sejam usados ao modificar sys.path. Se suas extensões personalizadas residem em um diretório relativo ao diretório de configuração, use pathlib.Path.resolve() assim:

import sys
from pathlib import Path

sys.path.append(str(Path('sphinxext').resolve()))

extensions = [
   ...
   'extname',
]

A estrutura de diretórios ilustrada acima ficaria assim:

<project directory>/
├── conf.py
└── sphinxext/
    └── extname.py

needs_extensions¶

Tipo:: dict[str, str]
Padrão:: {}

Se definido, este valor deve ser um dicionário especificando os requerimentos das extensões em extensions. As strings de versão devem estar no formato major.minor. Requerimentos não precisam ser especificado para todas as extensões, apenas para as que devem ser verificadas. Exemplo:

needs_extensions = {
    'sphinxcontrib.something': '1.5',
}

Isto requer que a extensão declare sua versão na função setup(). Veja API do Sphinx para mais detalhes.

Adicionado na versão 1.3.

manpages_url¶

Tipo:: str
Padrão:: ''

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: A página de manual (man)
section: A seção do manual (1)
path: path - a página de manual original e a seção especificada (man(1))

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

# To use manpages.debian.org:
manpages_url = 'https://manpages.debian.org/{path}'
# To use man7.org:
manpages_url = 'https://man7.org/linux/man-pages/man{section}/{page}.{section}.html'
# To use linux.die.net:
manpages_url = 'https://linux.die.net/man/{section}/{page}'
# To use helpmanual.io:
manpages_url = 'https://helpmanual.io/man{section}/{page}'

Adicionado na versão 1.7.

today¶

today_fmt¶

Esses valores determinam como formatar a data atual, usada como substituto para o substituto padrão |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 para today é '' e o padrão para today_fmt é '%b %d, %Y' (ou se tradução estiver habilitada com language, um formato será selecionado na localidade equivalente).

Opções para numeração de figuras¶

numfig¶

Tipo:: bool
Padrão:: False

Se True, figuras, tabelas e blocos de código são automaticamente numerados, caso tenham legenda. Se o papel numref estivar habilitada. Abrange atualmente os construtores de HTML e LaTeX.

Nota

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

Adicionado na versão 1.3.

numfig_format¶

Tipo:: dict[str, str]
Padrão:: {}

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

Os padrões são:

numfig_format = {
    'code-block': 'Listing %s',
    'figure': 'Fig. %s',
    'section': 'Section',
    'table': 'Table %s',
}

Adicionado na versão 1.3.

numfig_secnum_depth¶

Tipo:: int
Padrão:: 1

Se definido para 0, as figuras, os tabelas e os blocos de código são continuamente numerados iniciando em 1.
Se 1, a numeração será x.1, x.2, … com x representando o número da seção. (Se não houver seção de nível superior, o prefixo não será adicionado). Isso naturalmente se aplica, somente se numeração foi ativada através da opção :numbered: da diretiva toctree.
Se 2, a numeração será x.y.1, x.y.2, … com x representando o número da seção e y o número da subseção. Se localizado diretamente abaixo de uma seção, não haverá prefixo y., e se não houver seção de nível superior, o prefixo não será adicionado.
Qualquer outro número inteiro positivo pode ser utilizado, seguindo as regras acima.

Adicionado na versão 1.3.

Alterado na versão 1.7: O construtor LaTeX obedece essa configuração se numfig estiver definido para True.

Opções de realce¶

highlight_language¶

Tipo:: str
Padrão:: 'default'

A linguagem padrão para realçar o código-fonte. O padrão é 'default', que suprime avisos se o realce como código Python falhar.

O valor deve ser um nome de lexador válido do Pygments, veja Mostrando exemplos de código para mais detalhes.

Adicionado na versão 0.5.

Alterado na versão 1.4: O padrão é agora 'default'.

highlight_options¶

Tipo:: dict[str, dict[str, Any]]
Padrão:: {}

Um dicionário que mapeia nomes de analisadores léxicos de Pygments para suas opções. 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},
}

Adicionado na versão 1.3.

Alterado na versão 3.5: Permite configurar opções de realce para vários analisadores léxicos.

pygments_style¶

Tipo:: str
Padrão:: 'sphinx'

O nome do estilo usado para realce de código-fonte com Pygments. Se não definido, usa estilo padrão 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.

Opções para solicitações HTTP¶

tls_verify¶

Tipo:: bool
Padrão:: True

Se verdadeiro, o Sphinx verifica os certificados do servidor.

Adicionado na versão 1.5.

tls_cacerts¶

Tipo:: str | dict[str, str]
Padrão:: ''

Caminho para um arquivo de certificado de AC ou caminho para o diretório que contém os certificados. Também permite um dicionário mapeando nomes do host para o caminho do arquivo de certificado. Os certificados são usados para verificar os certificados do servidor.

Adicionado na versão 1.5.

Dica

O Sphinx usa requests como uma biblioteca HTTP internamente. Se tls_cacerts não estiver definido, o Sphinx volta ao comportamento padrão do requests. Veja SSL Cert Verification para mais detalhes.

user_agent¶

Tipo:: str
Padrão:: 'Mozilla/5.0 (X11; Linux x86_64; rv:100.0) Gecko/20100101 Firefox/100.0 Sphinx/X.Y.Z'

Define o User-Agent usado pelo Sphinx para solicitações HTTP.

Adicionado na versão 2.3.

Opções para internacionalização¶

Essas opções influenciam no Native Language Support (que, em português, significa “suporte a idioma nativo”) do Sphinx. Veja a documentação em Internacionalização para detalhes.

language¶

Tipo:: str
Padrão:: 'en'

O código para o idioma em que os documentos são escritos. Qualquer texto gerado automaticamente pelo Sphinx estará nesse idioma. Além disso, o Sphinx tentará substituir parágrafos individuais de seus documentos com os conjuntos de tradução obtidos em locale_dirs. O Sphinx irá pesquisar figuras específicas de um idioma nomeadas por figure_language_filename (por exemplo, a versão alemã de myfigure.png será myfigure.de.png por padrão) e as substituirá por figuras originais. No construtor LaTeX, um idioma adequado será selecionado como uma opção para o pacote Babel.

Adicionado na versão 0.5.

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

Alterado na versão 5.0: O padrão agora é 'en' (anteriormente None).

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 – Inglês (padrão)
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¶

Tipo:: list[str]
Padrão:: ['locales']

Diretórios para pesquisar por catálogos de mensagens adicionais (veja language), relativos ao diretório fonte. Os diretórios desse caminho de pesquisa serão usados pelo módulo gettext.

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

Nota

A opção -v do sphinx-build é útil para verificar se a configuração locale_dirs está funcionando conforme o esperado. Se o diretório do catálogo de mensagens não for encontrado, mensagens de depuração serão emitidas.

Adicionado na versão 0.5.

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

gettext_allow_fuzzy_translations¶

Tipo:: bool
Padrão:: False

Se True, as mensagens aproximadas, isto é, marcadas com “fuzzy” nos catálogos de mensagens são usadas para tradução.

Adicionado na versão 4.3.

gettext_compact¶

Tipo:: bool | str
Padrão:: True

Se True, o domínio de texto de um documento será seu docname se for um arquivo de projeto de nível superior e, caso contrário, seu diretório base.
Se False, o domínio de texto de um documento é o docname, por extenso.
Se definido com uma string, o domínio de texto de todos os documentos é esta string, fazendo com que todos os documentos usem um único domínio de texto.

Com gettext_compact = True, o documento markup/code.rst termina no domínio de texto markup. Com esta opção definida como False, é markup/code. Com esta opção definida como 'sample', é sample.

Adicionado na versão 1.1.

Alterado na versão 3.3: Permite valores de string.

gettext_uuid¶

Tipo:: bool
Padrão:: False

Se True, Sphinx gera informação UUID para rastrear versão os catálogos de mensagens. Usado para:

Adiciona uma linha de UUID para cada msgid nos arquivos .pot.
Calcula a similaridade entre novas msgids e as anteriormente salvas msgids antigas. (Esse cálculo pode levar algum tempo.)

Dica

Se deseja acelerar o cálculo, pode usar um pacote de terceiros (Levenshtein) executando pip install levenshtein.

Adicionado na versão 1.3.

gettext_location¶

Tipo:: bool
Padrão:: True

Se True, Sphinx gera informação de local de mensagens em catálogos de mensagens.

Adicionado na versão 1.3.

gettext_auto_build¶

Tipo:: bool
Padrão:: True

Se True, Sphinx constrói um arquivo .mo para cada catálogo de mensagens.

Adicionado na versão 1.3.

gettext_additional_targets¶

Tipo:: set[str] | Sequence[str]
Padrão:: []

Habilita a tradução gettext para certos tipos de elementos. Exemplo:

gettext_additional_targets = {'literal-block', 'image'}

Os seguintes tipos de elementos são suportados:

'index' – termos de índice
'literal-block' – blocos literais (anotação :: e diretiva code-block)
'doctest-block' – bloco de doctest
'raw' – conteúdo bruto
'image' – uri de imagem/figura

Adicionado na versão 1.3.

Alterado na versão 4.0: O texto alternativo de imagens é traduzido por padrão.

Alterado na versão 7.4: Permite e prefere um tipo definido.

figure_language_filename¶

Tipo:: str
Padrão:: '{root}.{language}{ext}'

O formato do nome do arquivo para figuras específicas de idioma. Os tokens de formato disponíveis são:

{root}: o nome do arquivo, incluindo componentes de caminho, porem sem a extensão do arquivo. Por exemplo: images/filename.
{path}: o caminho do diretório do nome do arquivo, com barra final se não for vazio. Por exemplo: images/.
{basename}: nome do arquivo sem o caminho do diretório e sem a extensão do arquivo. Por exemplo: filename.
{ext}: a extensão do arquivo. Por exemplo: .png.
{language}: idioma da tradução. Por exemplo: en.
{docpath}: o caminho do diretório do documento atual, com barra final se não for vazio. Por exemplo: dirname/.

Por padrão, uma diretiva de imagem .. image:: images/filename.png, usando uma imagem em images/filename.png, usará um nome de arquivo da figura específico do idioma images/filename.en.png.

Se figure_language_filename for definido como abaixo, o nome do arquivo da figura específico do idioma será images/en/filename.png.

figure_language_filename = '{path}{language}/{basename}{ext}'

Adicionado 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¶

Tipo:: bool | 'translated' | 'untranslated'
Padrão:: False

Controla quais classes serão adicionadas, se houver, para indicar o progresso da tradução. Esta configuração provavelmente seria usada apenas por tradutores de documentação, para indicar rapidamente o conteúdo traduzido e não traduzido.

True: Adiciona as classes translated e untranslated para todos os nós com conteúdo traduzido.
'translated': Adiciona apenas a classe translated.
'untranslated': Adiciona apenas a classe untranslated.
False: Não adiciona qualquer classe para indicar o progresso de tradução. not add any classes to indicate translation progress.

Adicionado na versão 7.1.

Opções para marcação¶

default_role¶

Tipo:: str
Padrão:: None

O nome de um papel reStructuredText (embutido ou extensão Sphinx) para usar o papel padrão, isso é, para o texto marcado `como esse`. Pode ser definido para 'py:obj' para tornar `filter` uma referência cruzada para a função Python “filter”.

O papel padrão pode ser sempre definido dentro de documentos individuais usando a diretiva reStructuredText default-role.

Adicionado na versão 0.4.

keep_warnings¶

Tipo:: bool
Padrão:: False

Mantém os avisos como parágrafos de “mensagens do sistema” nos documentos renderizados. Os avisos são sempre escritos no fluxo de erros padrão quando sphinx-build é executado, independentemente desta configuração.

Adicionado na versão 0.5.

option_emphasise_placeholders¶

Tipo:: bool
Padrão:: False

Quando habilitado, enfatiza os espaços reservados nas diretivas option. Para exibir chaves literais, escape com uma barra invertida (\{). Por exemplo, option_emphasise_placeholders=True e .. option:: -foption={TYPE} seriam renderizados com TYPE enfatizado.

Adicionado na versão 5.1.

primary_domain¶

Tipo:: str
Padrão:: 'py'

O nome do domínio padrão. Também pode ser None para desabilitar um domínio padrão. O padrão é 'py', para o domínio Python.

Esses objetos em outro domínio (onde o nome de domínio é dado explicitamente ou selecionado por uma diretiva default-domain) irá ter o nome de domínio prefixado quando renomeado (por exemplo, quando o domínio padrão é C, as funções Python serão nomeadas “função Python”, não “função”). Exemplo:

primary_domain = 'cpp'

Adicionado na versão 1.0.

rst_epilog¶

Tipo:: str
Padrão:: ''

Uma string de reStructuredText que pode ser incluída ao final de todo arquivo 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
"""

Adicionado na versão 0.6.

rst_prolog¶

Tipo:: str
Padrão:: ''

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
"""

Adicionado na versão 1.0.

show_authors¶

Tipo:: bool
Padrão:: False

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

trim_footnote_reference_space¶

Tipo:: bool
Padrão:: False

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

Adicionado na versão 0.6.

Opções para matemática¶

Essas opções controlam a marcação e notação matemática.

math_eqref_format¶

Tipo:: str
Padrão:: '({number})'

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.

Adicionado na versão 1.7.

math_number_all¶

Tipo:: bool
Padrão:: False

Força todas as equações exibidas a serem numeradas. Exemplo:

math_number_all = True

Adicionado na versão 1.4.

math_numfig¶

Tipo:: bool
Padrão:: True

Se True, 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. O papel eq, e não numref, deve ser usado para referenciar número de equações.

Adicionado na versão 1.7.

math_numsep¶

Tipo:: str
Padrão:: '.'

Uma string que define o separador entre os números da seção e o número da equação quando numfig está habilitada e numfig_secnum_depth é positiva.

Exemplo: '-' é renderizado como 1.2-3.

Adicionado na versão 7.4.

Opções para modo nitpicky¶

nitpicky¶

Tipo:: bool
Padrão:: False

Habilita o modo nitpicky se True. No modo nitpicky (em português, minuncioso), o Sphinx avisará sobre todas as referências onde o alvo não pode ser encontrado. Isto é recomendado para novos projetos, pois garante que todas as referências sejam a metas válidas.

Você pode ativar este modo temporariamente usando a opção de linha de comando --nitpicky. Veja nitpick_ignore para uma maneira de marcar referências ausentes como “sabidamente ausentes”.

nitpicky = True

Adicionado na versão 1.0.

nitpick_ignore¶

Tipo:: set[tuple[str, str]] | Sequence[tuple[str, str]]
Padrão:: ()

Um conjunto ou lista de tuplas (warning_type, target) que devem ser ignoradas ao gerar avisos no "modo nitpicky". Observe que warning_type deve incluir o nome do domínio, se presente. Exemplo:

nitpick_ignore = {
    ('py:func', 'int'),
    ('envvar', 'LD_LIBRARY_PATH'),
}

Adicionado na versão 1.1.

Alterado na versão 6.2: Tipos de contêiner permitidos alterados para conjunto, lista ou tupla

nitpick_ignore_regex¶

Tipo:: set[tuple[str, str]] | Sequence[tuple[str, str]]
Padrão:: ()

Uma versão estendida da nitpick_ignore, que interpreta as strings warning_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.*') vai ignorar avisos nitpicky 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').

Adicionado na versão 4.1.

Alterado na versão 6.2: Tipos de contêiner permitidos alterados para conjunto, lista ou tupla

Opções para assinaturas de objetos¶

add_function_parentheses¶

Tipo:: bool
Padrão:: True

Booleano que decide onde parênteses são anexados a texto de papéis de função ou método (por exemplo, conteúdo de :func:`input`) para significar que o nome é chamável.

maximum_signature_line_length¶

Tipo:: int | None
Padrão:: None

Se o comprimento de uma assinatura em caracteres exceder o número definido, cada parâmetro dentro da assinatura será exibido em uma linha lógica individual.

Quando None, não há comprimento máximo e toda a assinatura será exibida em uma única linha lógica.

Uma “linha lógica” é semelhante a uma quebra de linha rígida — construtores ou temas podem optar por uma “quebra suavemente” de uma única linha lógica, e esta configuração não afeta esse comportamento.

Os domínios podem fornecer opções para suprimir qualquer quebra rígida em uma diretiva de objeto individual, como visto nos domínios C, C++ e Python (por exemplo, py:function:single-line-parameter-list).

Adicionado na versão 7.1.

strip_signature_backslash¶

Tipo:: bool
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.

Adicionado na versão 3.0.

toc_object_entries¶

Tipo:: bool
Padrão:: True

Cria entradas na tabela de conteúdo para objetos de domínio (por exemplo, funções, classes, atributos, etc.).

Adicionado na versão 5.2.

toc_object_entries_show_parents¶

Tipo:: 'domain' | 'hide' | 'all'
Padrão:: 'domain'

Uma string que determina como os objetos de domínio (funções, classes, atributos, etc.) são exibidos na entrada do índice.

Use 'domain' para permitir que o domínio determine o número apropriado de pais a serem exibidos. Por exemplo, o domínio Python mostraria Class.method() e function(), deixando de fora o nível module. dos pais. Esta é a configuração padrão.

Use 'hide' para mostrar apenas o nome do elemento sem nenhum pai (ou seja, method()).

Use 'all' para mostrar o nome totalmente qualificado do objeto (ou seja, module.Class.method()), exibindo todos os pais.

Adicionado na versão 5.2.

Opções de arquivos fonte¶

exclude_patterns¶

Tipo:: Sequence[str]
Padrão:: ()

Uma lista de padrões estilo glob que deve ser desconsiderada quando buscando arquivos fonte. Eles são verificados contra nomes de arquivo fonte relativos ao diretório fonte, usando barras com separador de diretório em todas as plataformas. exclude_patterns tem prioridade sobre include_patterns.

Padrões de exemplo:

'library/xml.rst' – ignora o arquivo de library/xml.rst
'library/xml' – ignora o diretório de library/xml
'library/xml*' – ignora todos os arquivos e diretórios iniciando com library/xml
'**/.git' – ignora todos diretórios .git
'Thumbs.db' – ignora todos diretórios Thumbs.db

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

Adicionado na versão 1.0.

include_patterns¶

Tipo:: Sequence[str]
Padrão:: ('**',)

Uma lista de padrões de estilo glob que são usados para encontrar arquivos fonte. Eles são comparados com os nomes dos arquivos de origem relativos ao diretório fonte, usando barras como separadores de diretório em todas as plataformas. Por padrão, todos os arquivos são incluídos recursivamente no diretório fonte. exclude_patterns tem prioridade sobre include_patterns.

Padrões de exemplo:

'**' – todos os arquivos no diretório fonte e subdiretórios, recursivamente
'library/xml' – apenas o diretório de library/xml
'library/xml*' – todos os arquivos e diretórios iniciando com library/xml
'**/doc' – todos os diretórios doc (isso pode ser útil se a documentação estiver co-localizada com arquivos fonte)

Adicionado na versão 5.1.

master_doc¶

root_doc¶

Tipo:: str
Padrão:: 'index'

O Sphinx constrói uma árvore de documentos baseada nas diretivas toctree contidas nos arquivos fonte. Isto define o nome do documento que contém a diretiva mestre toctree e, portanto, a raiz de toda a árvore. Exemplo:

master_doc = 'contents'

Alterado na versão 2.0: O padrão é 'index' (anteriormente 'contents').

Adicionado na versão 4.0: O apelido root_doc.

source_encoding¶

Tipo:: str
Padrão:: 'utf-8-sig'

A codificação de arquivo de todos arquivos fonte. A codificação recomendada é 'utf-8-sig'.

Adicionado na versão 0.5.

source_suffix¶

Tipo:: dict[str, str] | Sequence[str] | str
Padrão:: {'.rst': 'restructuredtext'}

Um dicionário que mapeia as extensões de arquivo (sufixos) dos arquivos fonte para seus tipos de arquivo. O Sphinx considera todos os arquivos com sufixos em source_suffix como arquivos fonte. Exemplo:

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

Por padrão, o Sphinx dá suporte apenas ao tipo de arquivo 'restructuredtext'. Outros tipos de arquivos podem ser adicionados com extensões que registram diferentes analisadores de arquivos fonte, como MyST-Parser. Consulte a documentação da extensão para ver a quais tipos de arquivo ela tem suporte.

Se o valor for uma string ou sequência de strings, o Sphinx considerará que todos eles são arquivos 'restructuredtext'.

Nota

As extensões de arquivo devem começar com um ponto ('.').

Alterado na versão 1.3: Suporte a uma lista de extensões de arquivos.

Alterado na versão 1.8: Muda para um mapa de extensões de arquivo para tipos de arquivo.

Opções para aspas inteligentes¶

smartquotes¶

Tipo:: bool
Padrão:: True

Se True, a transformação Smart Quotes será usada para converter aspas e travessões em entidades tipograficamente corretas.

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

Nota

Um arquivo docutils.conf localizado no diretório de configuração (ou em um arquivo global ~/.docutils) é respeitado incondicionalmente se ele desativa aspas inteligentes através da correspondente opção do Docutils. Mas se ativa, então smartquotes, não prevalece.

smartquotes_action¶

Tipo:: str
Padrão:: 'qDe'

Personaliza a transformação Smart Quotes (aspas inteligentes). Veja abaixo os códigos permitidos. O padrão 'qDe' educa os caracteres normais de aspas (quote) ", ', travessão e meia-risca (em- e en-Dashes) ---, --, e reticências (ellipses) .....

'q': Converte aspas simples e duplas comuns
'b': Converte aspas com sinal de crase ou backticks (``duplas'' apenas)
'B': Converte aspas com sinal de crase ou backticks (``duplas'' e `simples')
'd': Converte traços (converte -- para travessões e --- para meia-risca)
'D': Converte traços no modo “das antigas” (converte -- para meia-risca e --- para travessões)
'i': Converte traços no modo “das antigas” invertido (converte -- para travessões e --- para meia-risca)
'e': Converte reticências ...
'w': Converte entidades '"' para '"'

Adicionado na versão 1.6.6.

smartquotes_excludes¶

Tipo:: dict[str, list[str]]
Padrão:: {'languages': ['ja'], 'builders': ['man', 'text']}

Contra quando a transformação Smart Quotes está desabilitada. As chaves permitidas são 'builders' e 'languages', e os valores são listas de strings.

Cada entrada fornece uma condição suficiente para ignorar a configuração smartquotes e desativar a transformação Smart Quotes. Exemplo:

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

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 SPHINXOPTS="-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 fonte 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 SPHINXOPTS="-D smartquotes_action="

Isto pode seguir algum make html sem problemas, em contraste com a situação da nota anterior.

Adicionado na versão 1.6.6.

Opções de temas¶

template_bridge¶

Tipo:: str
Padrão:: ''

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

template_bridge = 'module.CustomTemplateBridge'

templates_path¶

Tipo:: Sequence[str]
Padrão:: ()

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 de configuração. Exemplo:

templates_path = ['.templates']

Alterado na versão 1.3: Como esses arquivos não são destinados para serem construídos, eles são automaticamente excluídos ao descobrir arquivos fonte.

Opções para controle de avisos¶

show_warning_types¶

Tipo:: bool
Padrão:: True

Adiciona o tipo de cada aviso como sufixo à mensagem de aviso. Por exemplo, WARNING: [...] [index] ou WARNING: [...] [toc.circular]. Esta configuração pode ser útil para determinar quais tipos de avisos incluir em uma lista de suppress_warnings.

Adicionado na versão 7.3.0.

Alterado na versão 8.0.0: O padrão é agora True.

suppress_warnings¶

Tipo:: Sequence[str]
Padrão:: ()

Uma lista de códigos de aviso para suprimir mensagens de aviso arbitrárias.

Por padrão, o Sphinx tem suporte aos seguintes códigos de aviso:

app.add_node
app.add_directive
app.add_role
app.add_generic_role
app.add_source_parser
config.cache
docutils
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.copy_overwrite
misc.highlighting_failure
toc.circular
toc.excluded
toc.no_title
toc.not_readable
toc.secnum

As extensões também podem definir seus próprios tipos de aviso. Aqueles definidos pelas extensões do sphinx.ext são:

autodoc
autodoc.import_object
autosectionlabel.<document name>
autosummary
autosummary.import_cycle
intersphinx.external

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

Adicionado 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: Adicionado autosectionlabel.<nome do documento>

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

Adicionado na versão 4.5: Adicionado i18n.inconsistent_references

Adicionado na versão 7.1: Adicionado index.

Adicionado na versão 7.3: Adicionado config.cache.

Adicionado na versão 7.3: Adicionado toc.no_title.

Adicionado na versão 8.0: Adicionado misc.copy_overwrite.

Opções do construtor¶

Opções para saída HTML¶

Essas opções influenciam a saída HTML. Vários outros construtores são derivados da saída HTML e também fazem uso dessas opções.

html_theme¶

Tipo:: str
Padrão:: 'alabaster'

O tema para saída HTML. Veja a seção de temas HTML.

Adicionado na versão 0.6.

Alterado na versão 1.3: O tema padrão é agora 'alabaster'.

html_theme_options¶

Tipo:: dict[str, Any]
Padrão:: {}

Um dicionário de opções que influenciam a aparência do tema selecionado. Estes são específicos do tema. As opções compreendidas pelos temas embutidos são descritas aqui.

Adicionado na versão 0.6.

html_theme_path¶

Tipo:: list[str]
Padrão:: []

Uma lista de caminhos que contêm temas personalizados, como subdiretórios ou arquivos zip. Caminhos relativos são considerados relativos ao diretório de configuração.

Adicionado na versão 0.6.

html_style¶

Tipo:: Sequence[str] | str
Padrão:: ()

Folhas de estilo para usar em páginas HTML. A folha de estilo fornecida pelo tema selecionado é usada por padrão. Um arquivo com esse nome deve existir no caminho static/ do Sphinx ou em um dos caminhos personalizados fornecidos em html_static_path. Se você deseja apenas adicionar ou substituir algumas coisas do tema, use CSS @import para importar a folha de estilo do tema.

Alterado na versão 5.1: O valor pode ser um iterável de strings.

html_title¶

Tipo:: str
Padrão:: 'project release documentation'

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

html_short_title¶

Tipo:: str
Padrão:: The value of html_title

Um “título” mais curto para documentação HTML. Isso é usado para links no cabeçalho e na documentaçõ de Ajuda em HTML.

Adicionado na versão 0.4.

html_baseurl¶

Tipo:: str
Padrão:: ''

O URL base que aponta para a raiz da documentação HTML. É usado para indicar o local do documento usando a relação de link canônico.

Adicionado na versão 1.8.

html_codeblock_linenos_style¶

Tipo:: 'inline' | 'table'
Padrão:: 'inline'

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>

Adicionado 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¶

Tipo:: dict[str, Any]
Padrão:: {}

Dicionário de valores para passar ao contexto do mecanismo de modelos para todas páginas. Valores simples podem ser usados nesse dicionário usando a opção de linha de comando --html-define do sphinx-build.

Adicionado na versão 0.5.

html_logo¶

Tipo:: str
Padrão:: ''

Se fornecido, deve ser o nome de um arquivo de imagem (caminho relativo ao diretório de configuração) que é o logotipo da documentação, 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.

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

Alterado na versão 4.0: Também aceita uma URL.

html_favicon¶

Tipo:: str
Padrão:: ''

Se fornecido, deve ser o nome de um arquivo de imagem (caminho relativo ao diretório de configuração) que é o favicon dos documentação, ou URL que aponta um arquivo de imagem para o favicon. Os navegadores usam isso como ícone para abas, janelas e favoritos. Deve ser um ícone de 16 por 16 pixels nos formatos de arquivo PNG, SVG, GIF ou ICO.

Exemplo:

html_favicon = 'static/favicon.png'

Adicionado na versão 0.4: O arquivo de imagem será copiado para _static, 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¶

Tipo:: Sequence[str | tuple[str, dict[str, str]]]
Padrão:: []

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'. O dicionário attributes é usado para os atributos da tag <link>.

Exemplo:

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

O atributo especial priority pode ser definido como um inteiro para carregar o arquivo CSS em um passo anterior ou posterior. Para mais informações, consulte Sphinx.add_css_file().

Adicionado na versão 1.8.

Alterado na versão 3.5: Suporte ao atributo priority.

html_js_files¶

Tipo:: Sequence[str | tuple[str, dict[str, str]]]
Padrão:: []

Uma lista de arquivos 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 um URI completo com esquema como 'https://example.org/script.js'. O dicionário attributes é usado para os atributos da tag <script>.

Exemplo:

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

Como um atributo especial, priority pode ser definido como um inteiro para carregar o arquivo JavaScript em um passo anterior ou posterior. Para mais informações, consulte Sphinx.add_js_file().

Adicionado na versão 1.8.

Alterado na versão 3.5: Suporte ao atributo priority.

html_static_path¶

Tipo:: list[str]
Padrão:: []

Lista de caminhos que contém arquivos estáticos (como folhas de estilo ou arquivos script). Relativos ao diretório de configuração. 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 explicitamente cada arquivo a esta configuração:

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

Uma abordagem alternativa é usar html_extra_path, que 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¶

Tipo:: list[str]
Padrão:: []

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 saída. 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.

Adicionado na versão 1.2.

Alterado na versão 1.4: Arquivos existentes nos diretórios extra poderão ser copiados para o diretório de saída. E referências excluídas exclude_patterns ao copiar arquivos e diretórios e desprezar quando padrões combinarem com as regras.

html_last_updated_fmt¶

Tipo:: str
Padrão:: None

Se definido, o registro de data e hora de ‘Última atualização em:’ é inserido no rodapé de página, usando formato strftime() dado. A string vazia é equivalente a '%b %d, %Y' (ou ao equivalente conforme a localidade).

html_last_updated_use_utc¶

Tipo:: bool
Padrão:: False

Usa GMT/UTC (+00:00) em vez do fuso horário local do sistema para o horário fornecido para html_last_updated_fmt. Isso é mais útil quando o formato usado inclui o horário.

html_permalinks¶

Tipo:: bool
Padrão:: True

Adiciona âncoras de link para cada ambiente de título e descrição.

Adicionado na versão 3.5.

html_permalinks_icon¶

Tipo:: str
Padrão:: '¶' (the paragraph sign)

Texto para âncoras de link para cada título e ambiente de descrição. Entidades HTML e Unicode são permitidas.

Adicionado na versão 3.5.

html_sidebars¶

Tipo:: dict[str, Sequence[str]]
Padrão:: {}

Um dicionário que define modelos de barra lateral personalizados, mapeando nomes de documentos para nomes de modelos.

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

Cada valor deve ser uma lista de strings que a lista completa de modelos de barra lateral para inclusão. Se todas ou algumas barras laterais padrão 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 embutidos usam modelos por padrão: 'localtoc.html', 'relations.html', 'sourcelink.html' e 'searchbox.html'.

Os modelos de barra lateral incluídos no Sphinx que podem ser renderizados são:

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': ['windows-sidebar.html', 'searchbox.html'],
}

Isso vai renderizar o modelo personalizado windows-sidebar.html e a caixa de pesquisa dentro da barra lateral de um dado documento e renderizar as barras laterais padrão para outras páginas (exceto a tabela local de conteúdo TOC que será substituída pela TOC global).

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

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

Obsoleto desde a versão 1.7: Um valor de string simples para html_sidebars será removido.

Alterado na versão 2.0: html_sidebars deve ser uma lista de strings e não aceita mais um único valor de string.

html_additional_pages¶

Tipo:: dict[str, str]
Padrão:: {}

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': 'custom-download.html.jinja',
}

Isso renderizará o modelo custom-download.html.jinja como a página download.html.

html_domain_indices¶

Tipo:: bool | Sequence[str]
Padrão:: True

Se True, gera índices específicos do domínio além do índice geral. Por exemplo, para o domínio Python, é um índice global de módulos.

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

Exemplo:

html_domain_indices = {
    'py-modindex',
}

Adicionado na versão 1.0.

Alterado na versão 7.4: Permite e prefere um tipo definido.

html_use_index¶

Tipo:: bool
Padrão:: True

Controla se um índice é adicionado aos documentos HTML.

Adicionado na versão 0.4.

html_split_index¶

Tipo:: bool
Padrão:: False

Gera duas versões do índice: uma como uma única página com todas as entradas e uma como uma página por letra inicial.

Adicionado na versão 0.4.

html_copy_source¶

Tipo:: bool
Padrão:: True

Se True, as fontes reStructuredText são incluídas no construtor HTML como _sources/docname

html_show_sourcelink¶

Tipo:: bool
Padrão:: True

Se True (e html_copy_source for verdadeiro também), links para fontes reStructuredText irão aparecer na barra lateral.

Adicionado na versão 0.6.

html_sourcelink_suffix¶

Tipo:: str
Padrão:: '.txt'

O sufixo a ser anexado aos links de fontes (veja html_show_sourcelink), a menos que os arquivos já tenham este sufixo.

Adicionado na versão 1.5.

html_use_opensearch¶

Tipo:: str
Padrão:: ''

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

Adicionado na versão 0.2.

html_file_suffix¶

Tipo:: str
Padrão:: '.html'

O sufixo do nome do arquivo (extensão de arquivo) para arquivos HTML gerados.

Adicionado na versão 0.4.

html_link_suffix¶

Tipo:: str
Padrão:: The value of html_file_suffix

O sufixo para links gerados para arquivos HTML. Destinado a suportar configurações de servidor mais esotéricas.

Adicionado na versão 0.6.

html_show_copyright¶

Tipo:: bool
Padrão:: True

Se True, “© Copyright …” é mostrado no rodapé de HTML, com o valor ou valores de copyright.

Adicionado na versão 1.0.

html_show_search_summary¶

Tipo:: bool
Padrão:: True

Mostra um resumo do resultado da pesquisa, ou seja, o texto em torno da palavra-chave.

Adicionado na versão 4.5.

html_show_sphinx¶

Tipo:: bool
Padrão:: True

Adiciona “Criado usando Sphinx” no rodapé HTML.

Adicionado na versão 0.4.

html_output_encoding¶

Tipo:: str
Padrão:: 'utf-8'

Codificação arquivos de saída HTML. Esse nome da codificação deve ser válido no Python e no valor de charset HTML.

Adicionado na versão 1.0.

html_compact_lists¶

Tipo:: bool
Padrão:: True

Se True, 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. Padrão: True.

Adicionado na versão 1.0.

html_secnumber_suffix¶

Tipo:: str
Padrão:: '. '

Sufixo para números de seção na saída HTML. Defina como ' ' para suprimir o ponto final nos números de seção.

Adicionado na versão 1.0.

html_search_language¶

Tipo:: str
Padrão:: The value of language

Idioma a ser usado para gerar o índice de pesquisa de texto completo em HTML. O padrão é o idioma global selecionado com language. Inglês ('en') é usado se não houver suporte para o idioma informado.

Há suporte para os seguintes 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

Dica

Acelerando velocidade de montagem

Cada idioma (exceto Japonês) provê seu próprio algoritmo uso. Sphinx usa uma implementação Python por padrão. Se você quiser acelerar a construção do arquivo de índice, poderá usar um pacote de terceiros (PyStemmer) executando pip install PyStemmer.

Adicionado na versão 1.1: Suporte para inglês (en) e japonês (ja).

Alterado na versão 1.3: Adicionado outros idiomas.

html_search_options¶

Tipo:: dict[str, str]
Padrão:: {}

Um dicionário com opções de suporte a pesquisa em outros idiomas. O significado depende do idioma selecionado. Atualmente, somente japonês e chinês têm suporte a opções.

Japonês:

type – o tipo do divisor para usar.

As outras opções dependem do divisor usado.

'sphinx.search.ja.DefaultSplitter': O algoritmo TinySegmenter, usado por padrão.
'sphinx.search.ja.MecabSplitter':: A ligação MeCab. Para usar este divisor, é necessária a ligação python ‘mecab’ ou a biblioteca de ligação dinâmica (‘libmecab.so’ para Linux, ‘libmecab.dll’ para Windows).
'sphinx.search.ja.JanomeSplitter':: A ligação 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.

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:: A opção lib é 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’.

Chinês:

dict: O caminho de dicionário jieba para usar um dicionário personalizado.

Adicionado na versão 1.1.

Alterado na versão 1.4: Permite qualquer divisor personalizado na configuração type para japonês.

html_search_scorer¶

Tipo:: str
Padrão:: ''

O nome de um arquivo JavaScript (relativo ao diretório de configuração) que implementa um marcador de pontuação de resultados pesquisa. Se vazio, o padrão é usado.

O marcador de pontuação deve implementar a seguinte interface e pode, opcionalmente, definir a função score() para um controle mais granular.

const Scorer = {
    // Implement the following function to further tweak the score for each result
    score: result => {
      const [docName, title, anchor, descr, score, filename] = result

      // ... calculate a new score ...
      return score
    },

    // query matches the full name of an object
    objNameMatch: 11,
    // or matches in the last dotted part of the object name
    objPartialMatch: 6,
    // Additive scores depending on the priority of the object
    objPrio: {
      0: 15, // used to be importantResults
      1: 5, // used to be objectResults
      2: -5, // used to be unimportantResults
    },
    //  Used when the priority is not in the mapping.
    objPrioDefault: 0,

    // query found in title
    title: 15,
    partialTitle: 7,

    // query found in terms
    term: 5,
    partialTerm: 2,
};

Adicionado na versão 1.2.

html_scaled_image_link¶

Tipo:: bool
Padrão:: True

Vincula imagens que foram redimensionadas com uma opção de escala (scale, width ou height) à sua imagem original de resolução máxima. Isso não substituirá nenhum link fornecido pela opção target na diretiva image, se presente.

Dica

Para desabilitar esse recurso por imagem, adicione a classe no-scaled-link à diretiva de imagem:

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

Adicionado na versão 1.3.

Alterado na versão 3.0: Imagens com a classe no-scaled-link não serão vinculadas.

html_math_renderer¶

Tipo:: str
Padrão:: 'mathjax'

O renderizador matemático a ser usado para saída HTML. Os renderizadores agrupados são mathjax e imgmath. Você também deve carregar a extensão relevante em extensions.

Adicionado na versão 1.8.

Opções para saída Single HTML¶

Essas opções influenciam a saída Single HTML. Este construtor deriva do construtor HTML, então as opções HTML também se aplicam quando apropriado.

singlehtml_sidebars¶

Tipo:: dict[str, Sequence[str]]
Padrão:: The value of html_sidebars

Um dicionário que define modelos de barra lateral personalizados, mapeando nomes de documentos para nomes de modelos.

Isso tem o mesmo efeito que html_sidebars, mas a única chave permitida é 'index', e todas as outras chaves são ignoradas.

Opções para ajuda saída HTML¶

Essas opções influenciam a saída de ajuda HTML. Este construtor deriva do construtor HTML, então as opções HTML também se aplicam quando apropriado.

htmlhelp_basename¶

Tipo:: str
Padrão:: '{project}doc'

Emite o nome base do arquivo para o construtor de ajuda HTML. O padrão é nome do projeto com espaços removidos e doc anexado.

htmlhelp_file_suffix¶

Tipo:: str
Padrão:: '.html'

Este é o sufixo do nome do arquivo para arquivos de ajuda HTML gerados.

Adicionado na versão 2.0.

htmlhelp_link_suffix¶

Tipo:: str
Padrão:: The value of htmlhelp_file_suffix

Sufixo para links gerados para arquivos HTML.

Adicionado na versão 2.0.

Opções para saída Ajuda Apple¶

Adicionado 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 nos diretórios .lproj.

applehelp_bundle_name¶

Tipo:: str
Padrão:: The value of project

O nome base para o Apple Help Book. O padrão é nome do projeto com espaços removidos.

applehelp_bundle_id¶

Tipo:: str
Padrão:: None

O ID do Conjunto para livro de ajuda itens.

Aviso

Esse valor deve ser configurado para gerar Ajuda Apple.

applehelp_bundle_version¶

Tipo:: str
Padrão:: '1'

A versão empacotada, como um string.

applehelp_dev_region¶

Tipo:: str
Padrão:: 'en-us'

A região de desenvolvimento. Usa como padrão a configuração recomendada da Apple, 'en-us'.

applehelp_icon¶

Tipo:: str
Padrão:: None

O caminho para o 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¶

Tipo:: str
Padrão:: 'project-release'

A etiqueta produto usada com applehelp_kb_url.

applehelp_kb_url¶

Tipo:: str
Padrão:: None

A URL para seu servidor de base de conhecimento, por exemplo, https://example.com/kbsearch.py?p='product'&q='query'&l='lang'. Em tempo de execução, o Help Viewer substituirá 'product' pelo conteúdo de applehelp_kb_product, 'query' pelo texto inserido pelo usuário na caixa de pesquisa e 'lang' pelo idioma do sistema do usuário.

Defina isso para None para desabilitar a pesquisa remota.

applehelp_remote_url¶

Tipo:: str
Padrão:: None

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

Por exemplo, se você definir para``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.

Defina isso para None para nenhum conteúdo remoto.

applehelp_index_anchors¶

Tipo:: bool
Padrão:: False

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 ou o método openHelpAnchor:inBook: em seu código. Também possibilita uso de URLs help:anchor; veja a documentação Apple para maiores informações sobre esse tópico.

applehelp_min_term_length¶

Tipo:: str
Padrão:: None

Controla o tamanho mínimo para indexador de ajuda. Se None, usa o tamanho padrão.

applehelp_stopwords¶

Tipo:: str
Padrão:: The value of language

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:

Alemão (de)
Inglês (en)
Espanhol (es)
Francês (fr)
Húngaro (hu)
Italiano (it)
Sueco (sv)

applehelp_locale¶

Tipo:: str
Padrão:: The value of language

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

applehelp_title¶

Tipo:: str
Padrão:: 'project Help'

Especifica o título do livro de ajuda.

applehelp_codesign_identity¶

Tipo:: str
Padrão:: The value of CODE_SIGN_IDENTITY

Especifica a identidade a ser usada para assinatura de código. Use None se a assinatura de código não for realizada.

O padrão é o valor da variável de ambiente CODE_SIGN_IDENTITY, que é definida pelo Xcode para fases de construção de script, ou None se essa variável não estiver definida.

applehelp_codesign_flags¶

Tipo:: list[str]
Padrão:: The value of OTHER_CODE_SIGN_FLAGS

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

O padrão é uma lista baseada no valor da variável de ambiente OTHER_CODE_SIGN_FLAGS, que é definida pelo Xcode para fases de construção de script, ou a lista vazia se essa variável não estiver definida.

applehelp_codesign_path¶

Tipo:: str
Padrão:: '/usr/bin/codesign'

O caminho para o programa codesign.

applehelp_indexer_path¶

Tipo:: str
Padrão:: '/usr/bin/hiutil'

O caminho para o programa hiutil.

applehelp_disable_external_tools¶

Tipo:: bool
Padrão:: False

Não executa o indexador ou a ferramenta de assinatura de código, não importa quais outras configurações sejam especificadas.

Isso é útil principalmente para testes ou quando você deseja executar a construção do Sphinx em uma plataforma que não seja macOS e, por algum motivo, concluir as etapas finais em um Mac.

Opções para saída EPUB¶

Essas opções influenciam a saída de EPUB. Este construtor deriva do construtor HTML, então as opções HTML também se aplicam quando apropriado.

Nota

O valor real de algumas dessas opções não é importante, mas elas são necessárias para os metadados do Dublin Core.

epub_basename¶

Tipo:: str
Padrão:: The value of project

O nome base para o arquivo EPUB.

epub_theme¶

Tipo:: str
Padrão:: 'epub'

O tema HTML para a saída EPUB. Como os temas padrão não são otimizados para espaço de tela pequeno, usar o mesmo tema para saída HTML e EPUB geralmente não é sensato. O padrão é 'epub', um tema projetado para economizar espaço visual.

epub_theme_options¶

Tipo:: dict[str, Any]
Padrão:: {}

Um dicionário de opções que influenciam a aparência do tema selecionado. Estes são específicos do tema. As opções compreendidas pelos temas embutidos são descritas aqui.

Adicionado na versão 1.2.

epub_title¶

Tipo:: str
Padrão:: The value of project

O título do documento.

Alterado na versão 2.0: O padrão é a opção project (anteriormente html_title).

epub_description¶

Tipo:: str
Padrão:: 'unknown'

A descrição do documento.

Adicionado na versão 1.4.

Alterado na versão 1.5: Renomeada de epub3_description

epub_author¶

Tipo:: str
Padrão:: The value of author

O autor do documento. Isso é colocado em metadados Dublin Core.

epub_contributor¶

Tipo:: str
Padrão:: 'unknown'

O nome de uma pessoa, organização, etc. que desempenhou um papel secundário na criação do conteúdo de uma publicação EPUB.

Adicionado na versão 1.4.

Alterado na versão 1.5: Renomeada de epub3_contributor

epub_language¶

Tipo:: str
Padrão:: The value of language

Idioma do documento. Isso é colocado em metadados Dublin Core.

epub_publisher¶

Tipo:: str
Padrão:: The value of author

Editor ou publicador do documento. Isso é colocado metadados Dublin Core. Pode ser qualquer string, como página e nome projeto.

epub_copyright¶

Tipo:: str
Padrão:: The value of copyright

Os direitos autorais ou copyright do documento. Veja copyright para formatos permitidos.

epub_identifier¶

Tipo:: str
Padrão:: 'unknown'

Identificador para o documento. Isso é colocado nos metadados Dublin Core. Para documentos publicados é o número ISBN, mas pode ser usado um schema alternativo como, por exemplo, site do projeto.

epub_scheme¶

Tipo:: str
Padrão:: 'unknown'

Esquema da publicação para epub_identifier. Isso é colocado nos metadados do Dublin Core. Para livros publicados o esquema é 'ISBN'. Se usar o site do projeto, 'URL' parece razoável.

epub_uid¶

Tipo:: str
Padrão:: 'unknown'

Identificador único para o documento. Isso é colocado nos metadados Dublin Core. Pode ser usado uma string de formato de NOME do XML. Não pode conter hífen, ponto ou números como primeiro caractere.

epub_cover¶

Tipo:: tuple[str, str]
Padrão:: ()

Informação de rosto. É uma tupla contendo nomes de arquivo da imagem de rosto do modelo html. A página de rosto html renderizada é inserida como primeiro item no content.opf. Se o nome de arquivo do modelo estiver vazio, nenhuma página de rosto html será criada. Nenhuma capa será criada se a tupla estiver vazia.

Exemplos:

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

Adicionado na versão 1.1.

epub_css_files¶

Tipo:: Sequence[str | tuple[str, dict[str, str]]]
Padrão:: []

A list of CSS files. The entry must be a filename string or a tuple containing the filename string and the attributes dictionary. The filename must be relative to the html_static_path, or a full URI with scheme like 'https://example.org/style.css'. The attributes dictionary is used for the <link> tag’s attributes. For more information, see html_css_files.

Adicionado na versão 1.8.

epub_guide¶

Tipo:: Sequence[tuple[str, str, str]]
Padrão:: ()

Meta data for the guide element of content.opf. This is a sequence of tuples containing the type, the uri and the title of the optional guide information. See the OPF documentation for details. If possible, default entries for the cover and toc types are automatically inserted. However, the types can be explicitly overwritten if the default entries are not appropriate.

Exemplo:

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

O valor padrão é ().

epub_pre_files¶

Tipo:: Sequence[tuple[str, str]]
Padrão:: ()

Additional files that should be inserted before the text generated by Sphinx. It is a list of tuples containing the file name and the title. If the title is empty, no entry is added to toc.ncx.

Exemplo:

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

epub_post_files¶

Tipo:: Sequence[tuple[str, str]]
Padrão:: ()

Additional files that should be inserted after the text generated by Sphinx. It is a list of tuples containing the file name and the title. This option can be used to add an appendix. If the title is empty, no entry is added to toc.ncx.

Exemplo:

epub_post_files = [
    ('appendix.xhtml', 'Appendix'),
]

epub_exclude_files¶

Tipo:: Sequence[str]
Padrão:: []

A sequence of files that are generated/copied in the build directory but should not be included in the EPUB file.

epub_tocdepth¶

Tipo:: int
Padrão:: 3

The depth of the table of contents in the file toc.ncx. It should be an integer greater than zero.

Dica

A deeply nested table of contents may be difficult to navigate.

epub_tocdup¶

Tipo:: bool
Padrão:: True

This flag determines if a ToC entry is inserted again at the beginning of its nested ToC listing. This allows easier navigation to the top of a chapter, but can be confusing because it mixes entries of different depth in one list.

epub_tocscope¶

Tipo:: 'default' | 'includehidden'
Padrão:: 'default'

This setting control the scope of the EPUB table of contents. The setting can have the following values:

'default': Inclui todas as entradas de ToC não ocultas
'includehidden': Inclui todas as entradas de ToC

Adicionado na versão 1.2.

epub_fix_images¶

Tipo:: bool
Padrão:: False

Try and fix image formats that are not supported by some EPUB readers. At the moment palette images with a small colour table are upgraded. This is disabled by default because the automatic conversion may lose information. You need the Python Image Library (Pillow) installed to use this option.

Adicionado na versão 1.2.

epub_max_image_width¶

Tipo:: int
Padrão:: 0

This option specifies the maximum width of images. If it is set to a valuevgreater than zero, images with a width larger than the given value are scaled accordingly. If it is zero, no scaling is performed. You need the Python Image Library (Pillow) installed to use this option.

Adicionado na versão 1.2.

epub_show_urls¶

Tipo:: 'footnote' | 'no' | 'inline'
Padrão:: 'footnote'

Control how to display URL addresses. This is very useful for readers that have no other means to display the linked URL. The setting can have the following values:

'inline': Display URLs inline in parentheses.
'footnote': Display URLs in footnotes.
'no': Do not display URLs.

The display of inline URLs can be customised by adding CSS rules for the class link-target.

Adicionado na versão 1.2.

epub_use_index¶

Tipo:: bool
Padrão:: The value of html_use_index

Add an index to the EPUB document.

Adicionado na versão 1.2.

epub_writing_mode¶

Tipo:: 'horizontal' | 'vertical'
Padrão:: 'horizontal'

It specifies writing direction. It can accept 'horizontal' and 'vertical'

`epub_writing_mode`	`'horizontal'`	`'vertical'`
writing-mode	`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¶

Tipo:: 'pdflatex' | 'xelatex' | 'lualatex' | 'platex' | 'uplatex'
Padrão:: 'pdflatex'

The LaTeX engine to build the documentation. The setting can have the following values:

'pdflatex' – PDFLaTeX (default)
'xelatex' – XeLaTeX (default if language is one of el, zh_CN, or zh_TW)
'lualatex' – LuaLaTeX
'platex' – pLaTeX
'uplatex' – upLaTeX (default if language is 'ja')

Importante

'pdflatex'‘s support for Unicode characters is limited. If your project uses Unicode characters, setting the engine to 'xelatex' or 'lualatex' and making sure to use an OpenType font with wide-enough glyph coverage is often easier than trying to make 'pdflatex' work with the extra Unicode characters. Since Sphinx 2.0, the default typeface is GNU FreeFont, which has good coverage of Latin, Cyrillic, and Greek glyphs.

Nota

Sphinx 2.0 adds support for occasional Cyrillic and Greek letters or words in documents using a Latin language and 'pdflatex'. To enable this, the 'fontenc' key of latex_elements must be used appropriately.

Nota

Contrarily to MathJaX math rendering in HTML output, LaTeX requires some extra configuration to support Unicode literals in math: the only comprehensive solution (as far as we know) is to use 'xelatex' or 'lualatex' and to add r'\usepackage{unicode-math}' (e.g. via the 'preamble' key of latex_elements). You may prefer r'\usepackage[math-style=literal]{unicode-math}' to keep a Unicode literal such as α (U+03B1) as-is in output, rather than being rendered as $\alpha$.

Alterado na versão 2.1.0: Use 'xelatex' (and LaTeX package xeCJK) by default for Chinese documents.

Alterado na versão 2.2.1: Use 'xelatex' by default for Greek documents.

Alterado na versão 2.3: Add 'uplatex' support.

Alterado na versão 4.0: Use 'uplatex' by default for Japanese documents.

latex_documents¶

Tipo:: Sequence[tuple[str, str, str, str, str, bool]]
Padrão:: The default 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 that specifies the document name of the LaTeX file’s master document. All documents referenced by the startdoc document in ToC trees will be included in the LaTeX file. (If you want to use the default master document for your LaTeX build, provide your master_doc here.)
targetname: Nome de arquivo do arquivo LaTeX no diretório de saída.
title: LaTeX document title. Can be empty to use the title of the startdoc document. This is inserted as LaTeX markup, so special characters like a backslash or ampersand must be represented by the proper LaTeX commands if they are to be inserted literally.
author: Author for the LaTeX document. The same LaTeX markup caveat as for title applies. Use \\and to separate multiple authors, as in: 'John \\and Sarah' (backslashes must be Python-escaped to reach LaTeX).
theme: LaTeX theme. See latex_theme.
toctree_only: Must be True or False. If True, the startdoc document itself is not included in the output, only the documents referenced by it via ToC trees. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the LaTeX output.

Adicionado na versão 0.3: The 6th item toctree_only. Tuples with 5 items are still accepted.

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

latex_logo¶

Tipo:: str
Padrão:: ''

If given, this must be the name of an image file (path relative to the configuration directory) that is the logo of the documentation. It is placed at the top of the title page.

latex_toplevel_sectioning¶

Tipo:: 'part' | 'chapter' | 'section'
Padrão:: None

This value determines the topmost sectioning unit. The default setting is 'section' if latex_theme is 'howto', and 'chapter' if it is 'manual'. The alternative in both cases is to specify 'part', which means that LaTeX document will use the \part command.

In that case the numbering of sectioning units one level deep gets off-sync with HTML numbering, as by default LaTeX does not reset \chapter numbering (or \section for 'howto' theme) when encountering \part command.

Adicionado na versão 1.4.

latex_appendices¶

Tipo:: Sequence[str]
Padrão:: ()

A list of document names to append as an appendix to all manuals. This is ignored if latex_theme is set to 'howto'.

latex_domain_indices¶

Tipo:: bool | Sequence[str]
Padrão:: True

Se True, gera índices específicos do domínio além do índice geral. Por exemplo, para o domínio Python, é um índice global de módulos.

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

Exemplo:

latex_domain_indices = {
    'py-modindex',
}

Adicionado na versão 1.0.

Alterado na versão 7.4: Permite e prefere um tipo definido.

latex_show_pagerefs¶

Tipo:: bool
Padrão:: False

Add page references after internal references. This is very useful for printed copies of the manual.

Adicionado na versão 1.0.

latex_show_urls¶

Tipo:: 'no' | 'footnote' | 'inline'
Padrão:: 'no'

Control how to display URL addresses. This is very useful for printed copies of the manual. The setting can have the following values:

'no': Do not display URLs
'footnote': Display URLs in footnotes
'inline': Display URLs inline in parentheses

Adicionado na versão 1.0.

Alterado na versão 1.1: This value is now a string; previously it was a boolean value, and a true value selected the 'inline' display. For backwards compatibility, True is still accepted.

latex_use_latex_multicolumn¶

Tipo:: bool
Padrão:: False

Use standard LaTeX’s \multicolumn for merged cells in tables.

False: Sphinx’s own macros are used for merged cells from grid tables. They allow general contents (literal blocks, lists, blockquotes, …) but may have problems if the tabularcolumns directive was used to inject LaTeX mark-up of the type >{..}, <{..}, @{..} as column specification.
True: Use LaTeX’s standard \multicolumn; this is incompatible with literal blocks in horizontally merged cells, and also with multiple paragraphs in such cells if the table is rendered using tabulary.

Adicionado na versão 1.6.

latex_table_style¶

Tipo:: list[str]
Padrão:: ['booktabs', 'colorrows']

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 customise them is via dedicated keys of A definição da configuração sphinxsetup.

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 the latex table color configuration keys instead.

To customise the styles for a table, use the :class: option if the table is defined using a directive, or otherwise insert a rst-class directive before the table (cf. Tabelas).

Currently recognised 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 A definição da configuração sphinxsetup 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 in a table column specification like this:
```
>{\columncolor{blue}\sphinxnorowcolor}
```
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 descontinuadas section of this document in PDF format.

Dica

Se você quiser usar uma cor especial para o conteúdo das células de uma determinada coluna, use >{\noindent\color{<color>}}, possivelmente além do acima.
Células mescladas de várias linhas, sejam de coluna única ou de várias colunas, atualmente ignoram qualquer definição de coluna, linha ou cor de célula.
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

Em um documento que não usa 'booktabs' globalmente, é possível estilizar uma tabela individual através da classe booktabs, mas será necessário adicionar r'\usepackage{booktabs}' ao preâmbulo do LaTeX.

Por outro lado pode-se usar a classe colorrows para tabelas individuais sem nenhum pacote extra (já que o Sphinx desde a versão 5.3.0 sempre carrega colortbl).

Adicionado na versão 5.3.0.

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

latex_use_xindy¶

Tipo:: bool
Padrão:: True if latex_engine in {'xelatex', 'lualatex'} else False

Use Xindy to prepare the index of general terms. By default, the LaTeX builder uses makeindex for preparing the index of general terms . Using Xindy means that words with UTF-8 characters will be ordered correctly for the language.

This option is ignored if latex_engine is 'platex' (Japanese documents; mendex replaces makeindex then).
The default is True for 'xelatex' or 'lualatex' as makeindex creates .ind files containing invalid bytes for the UTF-8 encoding if any indexed term starts with a non-ASCII character. With 'lualatex' this then breaks the PDF build.
The default is False for 'pdflatex', but True is recommended for non-English documents as soon as some indexed terms use non-ASCII characters from the language script. Attempting to index a term whose first character is non-ASCII will break the build, if latex_use_xindy is left to its default False.

Sphinx adds some dedicated support to the xindy base distribution for using 'pdflatex' engine with Cyrillic scripts. With both 'pdflatex' and Unicode engines, Cyrillic documents handle the indexing of Latin names correctly, even those having diacritics.

Adicionado na versão 1.8.

latex_elements¶

Tipo:: dict[str, str]
Padrão:: {}

Adicionado na versão 0.5.

See the full documentation for latex_elements.

latex_docclass¶

Tipo:: dict[str, str]
Padrão:: {}

A dictionary mapping 'howto' and 'manual' to names of real document classes that will be used as the base for the two Sphinx classes. Default is to use 'article' for 'howto' and 'report' for 'manual'.

Adicionado na versão 1.0.

Alterado na versão 1.5: In Japanese documentation (language is 'ja'), by default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.

latex_additional_files¶

Tipo:: Sequence[str]
Padrão:: ()

A list of file names, relative to the configuration directory, to copy to the build directory when building LaTeX output. This is useful to copy files that Sphinx doesn’t copy automatically, or to overwrite Sphinx LaTeX support files with custom versions. Image files that are referenced in source files (e.g. via .. image::) are copied automatically and should not be listed there.

Atenção

Filenames with the .tex extension will be automatically 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 the \input{} macro accordingly.

Adicionado na versão 0.6.

Alterado na versão 1.2: This overrides the files provided from Sphinx such as sphinx.sty.

latex_theme¶

Tipo:: str
Padrão:: 'manual'

The “theme” that the LaTeX output should use. It is a collection of settings for LaTeX output (e.g. document class, top level sectioning unit and so on).

The bundled first-party LaTeX themes are manual and howto:

manual: A LaTeX theme for writing a manual. It imports the report document class (Japanese documents use jsbook).
howto: A LaTeX theme for writing an article. It imports the article document class (Japanese documents use jreport). latex_appendices is only available for this theme.

Adicionado na versão 3.0.

latex_theme_options¶

Tipo:: dict[str, Any]
Padrão:: {}

A dictionary of options that influence the look and feel of the selected theme. These are theme-specific.

Adicionado na versão 3.1.

latex_theme_path¶

Tipo:: list[str]
Padrão:: []

A list of paths that contain custom LaTeX themes as subdirectories. Relative paths are taken as relative to the configuration directory.

Adicionado na versão 3.0.

Opções para saída texto¶

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

text_add_secnumbers¶

Tipo:: bool
Padrão:: True

Include section numbers in text output.

Adicionado na versão 1.7.

text_newlines¶

Tipo:: 'unix' | 'windows' | 'native'
Padrão:: 'unix'

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

'unix': Use Unix-style line endings (\n).
'windows': Use Windows-style line endings (\r\n).
'native': Use the line ending style of the platform the documentation is built on.

Adicionado na versão 1.1.

text_secnumber_suffix¶

Tipo:: str
Padrão:: '. '

Suffix for section numbers in text output. Set to ' ' to suppress the final dot on section numbers.

Adicionado na versão 1.7.

text_sectionchars¶

Tipo:: str
Padrão:: '*=-~"+`'

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.

Adicionado na versão 1.1.

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

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

man_pages¶

Tipo:: Sequence[tuple[str, str, str, str, str]]
Padrão:: The default manual pages

This value determines how to group the document tree into manual pages. It must be a list of tuples (startdocname, name, description, authors, section), where the items are:

startdocname: String that specifies the document name of the manual page’s master document. All documents referenced by the startdoc document in ToC trees will be included in the manual page. (If you want to use the default master document for your manual pages build, provide your master_doc here.)
name: Name of the manual page. This should be a short string without spaces or special characters. It is used to determine the file name as well as the name of the manual page (in the NAME section).
description: Description of the manual page. This is used in the NAME section. Can be an empty string if you do not want to automatically generate the NAME section.
authors: A list of strings with authors, or a single string. Can be an empty string or list if you do not want to automatically generate an AUTHORS section in the manual page.
section: The manual page section. Used for the output file name as well as in the manual page header.

Adicionado na versão 1.0.

man_show_urls¶

Tipo:: bool
Padrão:: False

Add URL addresses after links.

Adicionado na versão 1.1.

man_make_section_directory¶

Tipo:: bool
Padrão:: True

Make a section directory on build man page.

Adicionado na versão 3.3.

Alterado na versão 4.0: The default is now False (previously True).

Alterado na versão 4.0.2: Revert the change in the default.

Opções para saída TexInfo¶

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

texinfo_documents¶

Tipo:: Sequence[tuple[str, str, str, str, str, str, str, bool]]
Padrão:: The default Texinfo documents

This value determines how to group the document tree into Texinfo source files. It must be a list of tuples (startdocname, targetname, title, author, dir_entry, description, category, toctree_only), where the items are:

startdocname: String that specifies the document name of the Texinfo file’s master document. All documents referenced by the startdoc document in ToC trees will be included in the Texinfo file. (If you want to use the default master document for your Texinfo build, provide your master_doc here.)
targetname: Nome de arquivo (sem extensão) do arquivo Texinfo no diretório de saída.
title: Texinfo document title. Can be empty to use the title of the startdoc document. Inserted as Texinfo markup, so special characters like @ and {} will need to be escaped to be inserted literally.
author: Author for the Texinfo document. Inserted as Texinfo markup. Use @* to separate multiple authors, as in: '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: Must be True or False. If True, the startdoc document itself is not included in the output, only the documents referenced by it via ToC trees. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the Texinfo output.

Adicionado na versão 1.1.

texinfo_appendices¶

Tipo:: Sequence[str]
Padrão:: []

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

Adicionado na versão 1.1.

texinfo_cross_references¶

Tipo:: bool
Padrão:: True

Generate inline references in a document. Disabling inline references can make an info file more readable with a stand-alone reader (info).

Adicionado na versão 4.4.

texinfo_domain_indices¶

Tipo:: bool | Sequence[str]
Padrão:: True

Se True, gera índices específicos do domínio além do índice geral. Por exemplo, para o domínio Python, é um índice global de módulos.

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

Exemplo:

texinfo_domain_indices = {
    'py-modindex',
}

Adicionado na versão 1.1.

Alterado na versão 7.4: Permite e prefere um tipo definido.

texinfo_elements¶

Tipo:: dict[str, Any]
Padrão:: {}

A dictionary that contains Texinfo snippets that override those that Sphinx usually puts into the generated .texi files.

Chaves que podem ser sobrepostas são:

'paragraphindent'
Number of spaces to indent the first line of each paragraph, default 2. Specify 0 for no indentation.

'exampleindent'
Number of spaces to indent the lines for examples or literal blocks, default 4. Specify 0 for no indentation.

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

'copying'
Texinfo markup inserted within the @copying block and displayed after the title. The default value consists of a simple title page identifying the project.
Keys that are set by other options and therefore should not be overridden are 'author', 'body', 'date', 'direntry' 'filename', 'project', 'release', and 'title'.

Adicionado na versão 1.1.

texinfo_no_detailmenu¶

Tipo:: bool
Padrão:: False

Do not generate a @detailmenu in the “Top” node’s menu containing entries for each sub-node in the document.

Adicionado na versão 1.2.

texinfo_show_urls¶

Tipo:: 'footnote' | 'no' | 'inline'
Padrão:: 'footnote'

Control how to display URL addresses. The setting can have the following values:

'footnote': Display URLs in footnotes.
'no': Do not display URLs.
'inline': Display URLs inline in parentheses.

Adicionado na versão 1.1.

Opções para saída QtHelp¶

These options influence qthelp output. This builder derives from the HTML builder, so the HTML options also apply where appropriate.

qthelp_basename¶

Tipo:: str
Padrão:: The value of project

The basename for the qthelp file.

qthelp_namespace¶

Tipo:: str
Padrão:: 'org.sphinx.{project_name}.{project_version}'

The namespace for the qthelp file.

qthelp_theme¶

Tipo:: str
Padrão:: 'nonav'

The HTML theme for the qthelp output.

qthelp_theme_options¶

Tipo:: dict[str, Any]
Padrão:: {}

Um dicionário de opções que influenciam a aparência do tema selecionado. Estes são específicos do tema. As opções compreendidas pelos temas embutidos são descritas aqui.

Options for XML output¶

xml_pretty¶

Tipo:: bool
Padrão:: True

Pretty-print the XML.

Adicionado na versão 1.2.

Opções para construtor linkcheck¶

Filtering¶

These options control which links the linkcheck builder checks, and which failures and redirects it ignores.

linkcheck_allowed_redirects¶

Tipo:: dict[str, str]
Padrão:: {}

A dictionary that maps a pattern of the source URI to a pattern of the canonical URI. The linkcheck builder treats the redirected link as “working” when:

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.

The linkcheck builder will emit a warning when it finds redirected links that don’t meet the rules above. It can be useful to detect unexpected redirects when using the fail-on-warnings mode.

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/.*'
}

Adicionado na versão 4.1.

linkcheck_anchors¶

Tipo:: bool
Padrão:: True

Check the validity of #anchors in links. Since this requires downloading the whole document, it is considerably slower when enabled.

Adicionado na versão 1.2.

linkcheck_anchors_ignore¶

Tipo:: Sequence[str]
Padrão:: ["^!"]

A list of regular expressions that match anchors that the linkcheck builder should skip when checking the validity of anchors in links. For example, this allows skipping anchors added by a website’s JavaScript.

Dica

Use linkcheck_anchors_ignore_for_url para verificar uma URL, mas pulando a verificação de se as âncoras existem.

Nota

If you want to ignore anchors of a specific page or of pages that match a specific pattern (but still check occurrences of the same page(s) that don’t have anchors), use linkcheck_ignore instead, for example as follows:

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

Adicionado na versão 1.5.

linkcheck_anchors_ignore_for_url¶

Tipo:: Sequence[str]
Padrão:: ()

A list or tuple of regular expressions matching URLs for which the linkcheck builder 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.

Adicionado na versão 7.1.

linkcheck_exclude_documents¶

Tipo:: Sequence[str]
Padrão:: ()

A list of regular expressions that match documents in which the linkcheck builder should not check the validity of links. This can be used for permitting link decay in legacy or historical sections of the documentation.

Exemplo:

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

Adicionado na versão 4.4.

linkcheck_ignore¶

Tipo:: Sequence[str]
Padrão:: ()

A list of regular expressions that match URIs that should not be checked when doing a linkcheck build.

Exemplo:

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

Adicionado na versão 1.1.

HTTP Requests¶

These options control how the linkcheck builder makes HTTP requests, including how it handles redirects and authentication, and the number of workers to use.

linkcheck_auth¶

Tipo:: Sequence[tuple[str, Any]]
Padrão:: []

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

A list of (regex_pattern, auth_info) tuples where the items are:

regex_pattern: Uma expressão regular que corresponde a uma URI.
auth_info: Authentication information to use for that URI. The value can be anything that is understood by the requests library (see requests authentication for details).

The linkcheck builder will use the first matching auth_info value it can find in the linkcheck_auth list, so values earlier in the list have higher priority.

Exemplo:

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

Adicionado na versão 2.3.

linkcheck_allow_unauthorized¶

Tipo:: bool
Padrão:: False

When a webserver responds with an HTTP 401 (unauthorised) response, the current default behaviour of the linkcheck builder is to treat the link as “broken”. To change that behaviour, set this option to True.

Alterado na versão 8.0: The default value for this option changed to False, meaning HTTP 401 responses to checked hyperlinks are treated as “broken” by default.

Adicionado na versão 7.3.

linkcheck_rate_limit_timeout¶

Tipo:: int
Padrão:: 300

The linkcheck builder may issue a large number of requests to the same site over a short period of time. This setting controls the builder behaviour when servers indicate that requests are rate-limited, by setting the maximum duration (in seconds) that the builder will wait for between each attempt before recording a failure.

The linkcheck builder always respects a server’s direction of when to retry (using the Retry-After header). Otherwise, linkcheck waits for a minute before to retry and keeps doubling the wait time between attempts until it succeeds or exceeds the linkcheck_rate_limit_timeout (in seconds). Custom timeouts should be given as a number of seconds.

Adicionado na versão 3.4.

linkcheck_report_timeouts_as_broken¶

Tipo:: bool
Padrão:: False

If linkcheck_timeout expires while waiting for a response from a hyperlink, the linkcheck builder will report the link as a timeout by default. To report timeouts as broken instead, you can set linkcheck_report_timeouts_as_broken to True.

Alterado na versão 8.0: The default value for this option changed to False, meaning timeouts that occur while checking hyperlinks will be reported using the new ‘timeout’ status code.

Adicionado na versão 7.3.

linkcheck_request_headers¶

Tipo:: dict[str, dict[str, str]]
Padrão:: {}

A dictionary that maps URL (without paths) to HTTP request headers.

The key is a URL base string like 'https://www.sphinx-doc.org/'. To specify headers for other hosts, "*" can be used. It matches all hosts only when the URL does not match other settings.

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",
    }
}

Adicionado na versão 3.1.

linkcheck_retries¶

Tipo:: int
Padrão:: 1

The number of times the linkcheck builder will attempt to check a URL before declaring it broken.

Adicionado na versão 1.4.

linkcheck_timeout¶

Tipo:: int
Padrão:: 30

The duration, in seconds, that the linkcheck builder will wait for a response after each hyperlink request.

Adicionado na versão 1.1.

linkcheck_workers¶

Tipo:: int
Padrão:: 5

The number of worker threads to use when checking links.

Adicionado na versão 1.1.

Domain options¶

Opções para o domínio C¶

c_extra_keywords¶

Tipo:: Set[str] | Sequence[str]
Padrão:: ['alignas', 'alignof', 'bool', 'complex', 'imaginary', 'noreturn', 'static_assert', 'thread_local']

A list of identifiers to be recognised as keywords by the C parser.

Adicionado na versão 4.0.3.

Alterado na versão 7.4: c_extra_keywords can now be a set.

c_id_attributes¶

Tipo:: Sequence[str]
Padrão:: ()

A sequence of strings that the parser should additionally accept as attributes. For example, this can be used when #define has been used for attributes, for portability.

Exemplo:

c_id_attributes = [
    'my_id_attribute',
]

Adicionado na versão 3.0.

Alterado na versão 7.4: c_id_attributes can now be a tuple.

c_maximum_signature_line_length¶

Tipo:: int | None
Padrão:: None

Se o comprimento de uma assinatura em caracteres exceder o número definido, cada parâmetro dentro da assinatura será exibido em uma linha lógica individual.

Quando None, não há comprimento máximo e toda a assinatura será exibida em uma única linha lógica.

This is a domain-specific setting, overriding maximum_signature_line_length.

Adicionado na versão 7.1.

c_paren_attributes¶

Tipo:: Sequence[str]
Padrão:: ()

A sequence of strings that the parser should additionally accept as attributes with one argument. That is, if my_align_as is in the list, then my_align_as(X) is parsed as an attribute for all strings X that have balanced braces ((), [], and {}). For example, this can be used when #define has been used for attributes, for portability.

Exemplo:

c_paren_attributes = [
    'my_align_as',
]

Adicionado na versão 3.0.

Alterado na versão 7.4: c_paren_attributes can now be a tuple.

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

cpp_id_attributes¶

Tipo:: Sequence[str]
Padrão:: ()

A sequence of strings that the parser should additionally accept as attributes. For example, this can be used when #define has been used for attributes, for portability.

Exemplo:

cpp_id_attributes = [
    'my_id_attribute',
]

Adicionado na versão 1.5.

Alterado na versão 7.4: cpp_id_attributes can now be a tuple.

cpp_index_common_prefix¶

Tipo:: Sequence[str]
Padrão:: ()

A list of prefixes that will be ignored when sorting C++ objects in the global index.

Exemplo:

cpp_index_common_prefix = [
    'awesome_lib::',
]

Adicionado na versão 1.5.

cpp_maximum_signature_line_length¶

Tipo:: int | None
Padrão:: None

Se o comprimento de uma assinatura em caracteres exceder o número definido, cada parâmetro dentro da assinatura será exibido em uma linha lógica individual.

Quando None, não há comprimento máximo e toda a assinatura será exibida em uma única linha lógica.

This is a domain-specific setting, overriding maximum_signature_line_length.

Adicionado na versão 7.1.

cpp_paren_attributes¶

Tipo:: Sequence[str]
Padrão:: ()

A sequence of strings that the parser should additionally accept as attributes with one argument. That is, if my_align_as is in the list, then my_align_as(X) is parsed as an attribute for all strings X that have balanced braces ((), [], and {}). For example, this can be used when #define has been used for attributes, for portability.

Exemplo:

cpp_paren_attributes = [
    'my_align_as',
]

Adicionado na versão 1.5.

Alterado na versão 7.4: cpp_paren_attributes can now be a tuple.

Opções para o domínio JavaScript¶

javascript_maximum_signature_line_length¶

Tipo:: int | None
Padrão:: None

Se o comprimento de uma assinatura em caracteres exceder o número definido, cada parâmetro dentro da assinatura será exibido em uma linha lógica individual.

Quando None, não há comprimento máximo e toda a assinatura será exibida em uma única linha lógica.

This is a domain-specific setting, overriding maximum_signature_line_length.

Adicionado na versão 7.1.

Opções para o domínio Python¶

add_module_names¶

Tipo:: bool
Padrão:: True

A boolean that decides whether module names are prepended to all object names (for object types where a “module” of some kind is defined), e.g. for py:function directives.

modindex_common_prefix¶

Tipo:: list[str]
Padrão:: []

A list of prefixes that are ignored for sorting the Python module index (e.g., if this is set to ['foo.'], then foo.bar is shown under B, not F). This can be handy if you document a project that consists of a single package.

Cuidado

Works only for the HTML builder currently.

Adicionado na versão 0.6.

python_display_short_literal_types¶

Tipo:: bool
Padrão:: False

This value controls how Literal types are displayed.

Exemplos¶

Os exemplos abaixo usam a seguinte diretiva py:function:

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

Adicionado na versão 6.2.

python_maximum_signature_line_length¶

Tipo:: int | None
Padrão:: None

Se o comprimento de uma assinatura em caracteres exceder o número definido, cada parâmetro dentro da assinatura será exibido em uma linha lógica individual.

Quando None, não há comprimento máximo e toda a assinatura será exibida em uma única linha lógica.

This is a domain-specific setting, overriding maximum_signature_line_length.

Para o domínio Python, o comprimento da assinatura depende se os parâmetros de tipo ou a lista de argumentos estão sendo formatados. Para o primeiro, o comprimento da assinatura ignora o comprimento da lista de argumentos; para este último, o comprimento da assinatura ignora o comprimento da lista de parâmetros de tipo.

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)

Adicionado na versão 7.1.

python_use_unqualified_type_names¶

Tipo:: bool
Padrão:: False

Suppress the module name of the python reference if it can be resolved.

Adicionado na versão 4.0.

Cuidado

This feature is experimental.

trim_doctest_flags¶

Tipo:: bool
Padrão:: True

Remove doctest flags (comments looking like # doctest: FLAG, ...) at the ends of lines and <BLANKLINE> markers for all code blocks showing interactive Python sessions (i.e. doctests). See the extension doctest for more possibilities of including doctests.

Adicionado na versão 1.0.

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

Opções Extensão¶

Extensions frequently have their own configuration options. Those for Sphinx’s first-party extensions are documented in each extension’s page.

Example configuration file¶

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'Test Project'
copyright = '2000-2042, The Test Project Authors'
author = 'The Authors'
version = release = '4.16'

# -- General configuration ------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

exclude_patterns = [
    '_build',
    'Thumbs.db',
    '.DS_Store',
]
extensions = []
language = 'en'
master_doc = 'index'
pygments_style = 'sphinx'
source_suffix = '.rst'
templates_path = ['_templates']

# -- Options for HTML output ----------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster'
html_static_path = ['_static']