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

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.

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 os.path.abspath() assim:

import os, sys; sys.path.append(os.path.abspath('sphinxext'))

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

These values determine how to format the current date, used as the replacement for the |today| default substitution.

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

The default for today is '', and the default for today_fmt is '%b %d, %Y' (or, if translation is enabled with language, an equivalent format for the selected locale).

Options for figure numbering

numfig
Tipo:
bool
Padrão:
False

If True, figures, tables and code-blocks are automatically numbered if they have a caption. The numref role is enabled. Obeyed so far only by HTML and LaTeX builders.

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:
{}

A dictionary mapping 'figure', 'table', 'code-block' and 'section' to strings that are used for format of figure numbers. The marker %s will be replaced with the figure number.

The defaults are:

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
  • If set to 0, figures, tables, and code-blocks are continuously numbered starting at 1.

  • If 1, the numbering will be x.1, x.2, … with x representing the section number. (If there is no top-level section, the prefix will not be added ). This naturally applies only if section numbering has been activated via the :numbered: option of the toctree directive.

  • If 2, the numbering will be x.y.1, x.y.2, … with x representing the section number and y the sub-section number. If located directly under a section, there will be no y. prefix, and if there is no top-level section, the prefix will not be added.

  • Any other positive integer can be used, following the rules above.

Adicionado na versão 1.3.

Alterado na versão 1.7: The LaTeX builder obeys this setting if numfig is set to True.

Options for highlighting

highlight_language
Tipo:
str
Padrão:
'default'

The default language to highlight source code in. The default is 'default', which suppresses warnings if highlighting as Python code fails.

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: The default is now 'default'.

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

A dictionary that maps Pygments lexer names to their options. These are lexer-specific; for the options understood by each, see the Pygments documentation.

Exemplo:

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

Adicionado na versão 1.3.

Alterado na versão 3.5: Allow configuring highlight options for multiple lexers.

pygments_style
Tipo:
str
Padrão:
'sphinx'

The style name to use for Pygments highlighting of source code. If not set, either the theme’s default style or 'sphinx' is selected for HTML output.

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.

Options for HTTP requests

tls_verify
Tipo:
bool
Padrão:
True

If True, Sphinx verifies server certificates.

Adicionado na versão 1.5.

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

A path to a certification file of CA or a path to directory which contains the certificates. This also allows a dictionary mapping hostnames to the certificate file path. The certificates are used to verify server certifications.

Adicionado na versão 1.5.

Dica

Sphinx uses requests as a HTTP library internally. If tls_cacerts is not set, Sphinx falls back to requests’ default behaviour. See SSL Cert Verification for further details.

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'

Set the User-Agent used by Sphinx for HTTP requests.

Adicionado na versão 2.3.

Options for internationalisation

These options influence Sphinx’s Native Language Support. See the documentation on Internacionalização for details.

language
Tipo:
str
Padrão:
'en'

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

Adicionado na versão 0.5.

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

Alterado na versão 5.0: The default is now 'en' (previously 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:
['locale']

Directories in which to search for additional message catalogs (see language), relative to the source directory. The directories on this path are searched by the gettext module.

Internal messages are fetched from a text domain of sphinx; so if you add the directory ./locale to this setting, the message catalogs (compiled from .po format using msgfmt) must be in ./locale/language/LC_MESSAGES/sphinx.mo. The text domain of individual documents depends on gettext_compact.

Nota

The -v option to sphinx-build is useful to check the locale_dirs setting is working as expected. If the message catalog directory not found, debug messages are emmitted.

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

If True, “fuzzy” messages in the message catalogs are used for translation.

Adicionado na versão 4.3.

gettext_compact
Tipo:
bool | str
Padrão:
True
  • If True, a document’s text domain is its docname if it is a top-level project file and its very base directory otherwise.

  • If False, a document’s text domain is the docname, in full.

  • If set to a string, every document’s text domain is set to this string, making all documents use single text domain.

With gettext_compact = True, the document markup/code.rst ends up in the markup text domain. With this option set to False, it is markup/code. With this option set to 'sample', it is sample.

Adicionado na versão 1.1.

Alterado na versão 3.3: Allow string values.

gettext_uuid
Tipo:
bool
Padrão:
False

If True, Sphinx generates UUID information for version tracking in message catalogs. It is used to:

  • Add a UUID line for each msgid in .pot files.

  • Calculate similarity between new msgids and previously saved old msgids. (This calculation can take a long time.)

Dica

If you want to accelerate the calculation, you can use a third-party package (Levenshtein) by running pip install levenshtein.

Adicionado na versão 1.3.

gettext_location
Tipo:
bool
Padrão:
True

If True, Sphinx generates location information for messages in message catalogs.

Adicionado na versão 1.3.

gettext_auto_build
Tipo:
bool
Padrão:
True

If True, Sphinx builds a .mo file for each translation catalog file.

Adicionado na versão 1.3.

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

Enable gettext translation for certain element types. Example:

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

The following element types are supported:

  • 'index' – index terms

  • 'literal-block' – literal blocks (:: annotation and code-block directive)

  • 'doctest-block' – doctest block

  • 'raw' – raw content

  • 'image' – image/figure uri

Adicionado na versão 1.3.

Alterado na versão 4.0: The alt text for images is translated by default.

Alterado na versão 7.4: Permit and prefer a set type.

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

The filename format for language-specific figures. The available format tokens are:

  • {root}: the filename, including any path component, without the file extension. For example: images/filename.

  • {path}: the directory path component of the filename, with a trailing slash if non-empty. For example: images/.

  • {basename}: the filename without the directory path or file extension components. For example: filename.

  • {ext}: the file extension. For example: .png.

  • {language}: the translation language. For example: en.

  • {docpath}: the directory path component for the current document, with a trailing slash if non-empty. For example: dirname/.

By default, an image directive .. image:: images/filename.png, using an image at images/filename.png, will use the language-specific figure filename images/filename.en.png.

If figure_language_filename is set as below, the language-specific figure filename will be images/en/filename.png instead.

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

Add translated and untranslated classes to all nodes with translatable content.

'translated'

Only add the translated class.

'untranslated'

Only add the untranslated class.

False

Do not add any classes to indicate translation progress.

Adicionado na versão 7.1.

Options for markup

default_role
Tipo:
str
Padrão:
None

The name of a reStructuredText role (builtin or Sphinx extension) to use as the default role, that is, for text marked up `like this`. This can be set to 'py:obj' to make `filter` a cross-reference to the Python function “filter”.

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

Adicionado na versão 0.4.

keep_warnings
Tipo:
bool
Padrão:
False

Keep warnings as “system message” paragraphs in the rendered documents. Warnings are always written to the standard error stream when sphinx-build is run, regardless of this setting.

Adicionado na versão 0.5.

option_emphasise_placeholders
Tipo:
bool
Padrão:
False

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

Adicionado na versão 5.1.

primary_domain
Tipo:
str
Padrão:
'py'

The name of the default domain. Can also be None to disable a default domain. The default is 'py', for the Python domain.

Those objects in other domain (whether the domain name is given explicitly, or selected by a default-domain directive) will have the domain name explicitly prepended when named (e.g., when the default domain is C, Python functions will be named “Python function”, not just “function”). Example:

primary_domain = 'cpp'

Adicionado na versão 1.0.

rst_epilog
Tipo:
str
Padrão:
''

A string of reStructuredText that will be included at the end of every source file that is read. This is a possible place to add substitutions that should be available in every file (another being rst_prolog). Example:

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

Adicionado na versão 0.6.

rst_prolog
Tipo:
str
Padrão:
''

A string of reStructuredText that will be included at the beginning of every source file that is read. This is a possible place to add substitutions that should be available in every file (another being rst_epilog). Example:

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

Trim spaces before footnote references that are necessary for the reStructuredText parser to recognise the footnote, but do not look too nice in the output.

Adicionado na versão 0.6.

Options for Maths

These options control maths markup and notation.

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

Force all displayed equations to be numbered. Example:

math_number_all = True

Adicionado na versão 1.4.

math_numfig
Tipo:
bool
Padrão:
True

If True, displayed math equations are numbered across pages when numfig is enabled. The numfig_secnum_depth setting is respected. The eq, not numref, role must be used to reference equation numbers.

Adicionado na versão 1.7.

math_numsep
Tipo:
str
Padrão:
'.'

A string that defines the separator between section numbers and the equation number when numfig is enabled and numfig_secnum_depth is positive.

Example: '-' gets rendered as 1.2-3.

Adicionado na versão 7.4.

Options for the nitpicky mode

nitpicky
Tipo:
bool
Padrão:
False

Enables nitpicky mode if True. In nitpicky mode, Sphinx will warn about all references where the target cannot be found. This is recommended for new projects as it ensures that all references are to valid targets.

You can activate this mode temporarily using the --nitpicky command-line option. See nitpick_ignore for a way to mark missing references as “known missing”.

nitpicky = True

Adicionado na versão 1.0.

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

A set or list of (warning_type, target) tuples that should be ignored when generating warnings in "nitpicky mode". Note that warning_type should include the domain name if present. Example:

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:
()

An extended version of nitpick_ignore, which instead interprets the warning_type and target strings as regular expressions. Note that the regular expression must match the whole string (as if the ^ and $ markers were inserted).

For example, (r'py:.*', r'foo.*bar\.B.*') will ignore nitpicky warnings for all python entities that start with 'foo' and have 'bar.B' in them, such as ('py:const', 'foo_package.bar.BAZ_VALUE') or ('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

Options for object signatures

add_function_parentheses
Tipo:
bool
Padrão:
True

A boolean that decides whether parentheses are appended to function and method role text (e.g. the content of :func:`input`) to signify that the name is callable.

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.

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

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

When backslash stripping is enabled then every occurrence of \\ in a domain directive will be changed to \, even within string literals. This was the behaviour before version 3.0, and setting this variable to True will reinstate that behaviour.

Adicionado na versão 3.0.

toc_object_entries
Tipo:
bool
Padrão:
True

Create table of contents entries for domain objects (e.g. functions, classes, attributes, etc.).

Adicionado na versão 5.2.

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

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

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

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

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

Adicionado na versão 5.2.

Options for source files

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

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

Padrões de exemplo:

  • 'library/xml.rst' – ignores the library/xml.rst file

  • 'library/xml' – ignores the library/xml directory

  • 'library/xml*' – ignores all files and directories starting with library/xml

  • '**/.git' – ignores all .git directories

  • 'Thumbs.db' – ignores all Thumbs.db files

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:
('**',)

A list of glob-style patterns that are used to find source files. They are matched against the source file names relative to the source directory, using slashes as directory separators on all platforms. By default, all files are recursively included from the source directory. exclude_patterns has priority over include_patterns.

Padrões de exemplo:

  • '**' – all files in the source directory and subdirectories, recursively

  • 'library/xml' – just the library/xml directory

  • 'library/xml*' – all files and directories starting with library/xml

  • '**/doc' – all doc directories (this might be useful if documentation is co-located with source files)

Adicionado na versão 5.1.

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

Sphinx builds a tree of documents based on the toctree directives contained within the source files. This sets the name of the document containing the master toctree directive, and hence the root of the entire tree. Example:

master_doc = 'contents'

Alterado na versão 2.0: Default is 'index' (previously 'contents').

Adicionado na versão 4.0: The root_doc alias.

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

The file encoding of all source files. The recommended encoding is 'utf-8-sig'.

Adicionado na versão 0.5.

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

A dictionary mapping the file extensions (suffixes) of source files to their file types. Sphinx considers all files files with suffixes in source_suffix to be source files. Example:

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

By default, Sphinx only supports the 'restructuredtext' file type. Further file types can be added with extensions that register different source file parsers, such as MyST-Parser. Refer to the extension’s documentation to see which file types it supports.

If the value is a string or sequence of strings, Sphinx will consider that they are all 'restructuredtext' files.

Nota

File extensions must begin with a dot ('.').

Alterado na versão 1.3: Support a list of file extensions.

Alterado na versão 1.8: Change to a map of file extensions to file types.

Options for smart quotes

smartquotes
Tipo:
bool
Padrão:
True

If True, the Smart Quotes transform will be used to convert quotation marks and dashes to typographically correct entities.

Adicionado na versão 1.6.6: Replaces the now-removed html_use_smartypants. It applies by default to all builders except man and text (see smartquotes_excludes.)

Nota

A docutils.conf file located in the configuration directory (or a global ~/.docutils file) is obeyed unconditionally if it deactivates smart quotes via the corresponding Docutils option. But if it activates them, then smartquotes does prevail.

smartquotes_action
Tipo:
str
Padrão:
'qDe'

Customise the Smart Quotes transform. See below for the permitted codes. The default 'qDe' educates normal quote characters ", ', em- and en-Dashes ---, --, and ellipses .....

'q'

Convert quotation marks

'b'

Convert backtick quotation marks (``double'' only)

'B'

Convert backtick quotation marks (``double'' and `single')

'd'

Convert dashes (convert -- to em-dashes and --- to en-dashes)

'D'

Convert dashes (old school) (convert -- to en-dashes and --- to em-dashes)

'i'

Convert dashes (inverted old school) (convert -- to em-dashes and --- to en-dashes)

'e'

Convert ellipses ...

'w'

Convert '&quot;' entities to '"'

Adicionado na versão 1.6.6.

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

Control when the Smart Quotes transform is disabled. Permitted keys are 'builders' and 'languages', and The values are lists of strings.

Each entry gives a sufficient condition to ignore the smartquotes setting and deactivate the Smart Quotes transform. Example:

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

Nota

Currently, in case of invocation of make with multiple targets, the first target name is the only one which is tested against the 'builders' entry and it decides for all. Also, a make text following make html needs to be issued in the form make text SPHINXOPTS="-E" to force re-parsing of source files, as the cached ones are already transformed. On the other hand the issue does not arise with direct usage of sphinx-build as it caches (in its default usage) the parsed source files in per builder locations.

Dica

An alternative way to effectively deactivate (or customise) the smart quotes for a given builder, for example latex, is to use make this way:

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.

Options for templating

template_bridge
Tipo:
str
Padrão:
''

A string with the fully-qualified name of a callable (or simply a class) that returns an instance of TemplateBridge. This instance is then used to render HTML documents, and possibly the output of other builders (currently the changes builder). (Note that the template bridge must be made theme-aware if HTML themes are to be used.) Example:

template_bridge = 'module.CustomTemplateBridge'
templates_path
Tipo:
Sequence[str]
Padrão:
()

A list of paths that contain extra templates (or templates that overwrite builtin/theme-specific templates). Relative paths are taken as relative to the configuration directory. Example:

templates_path = ['.templates']

Alterado na versão 1.3: As these files are not meant to be built, they are automatically excluded when discovering source files.

Options for warning control

show_warning_types
Tipo:
bool
Padrão:
False

Add the type of each warning as a suffix to the warning message. For example, WARNING: [...] [index] or WARNING: [...] [toc.circular]. This setting can be useful for determining which warnings types to include in a suppress_warnings list.

Adicionado na versão 7.3.0.

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

A list of warning codes to suppress arbitrary warning messages.

By default, Sphinx supports the following warning codes:

  • app.add_node

  • app.add_directive

  • app.add_role

  • app.add_generic_role

  • app.add_source_parser

  • config.cache

  • download.not_readable

  • epub.unknown_project_files

  • epub.duplicated_toc_entry

  • i18n.inconsistent_references

  • index

  • image.not_readable

  • ref.term

  • ref.ref

  • ref.numref

  • ref.keyword

  • ref.option

  • ref.citation

  • ref.footnote

  • ref.doc

  • ref.python

  • misc.highlighting_failure

  • toc.circular

  • toc.excluded

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

  • 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: Added index.

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

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

Builder options

Opções para saída HTML

These options influence HTML output. Various other builders are derived from the HTML output, and also make use of these options.

html_theme
Tipo:
str
Padrão:
'alabaster'

The theme for HTML output. See the HTML theming section.

Adicionado na versão 0.6.

Alterado na versão 1.3: The default theme is now 'alabaster'.

html_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. The options understood by the builtin themes are described here.

Adicionado na versão 0.6.

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

A list of paths that contain custom themes, either as subdirectories or as zip files. Relative paths are taken as relative to the configuration directory.

Adicionado na versão 0.6.

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

Stylesheets to use for HTML pages. The stylesheet given by the selected theme is used by default A file of that name must exist either in Sphinx’s static/ path or in one of the custom paths given in html_static_path. If you only want to add or override a few things from the theme, use CSS @import to import the theme’s stylesheet.

Alterado na versão 5.1: The value can be a iterable of strings.

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

The “title” for HTML documentation generated with Sphinx’s own templates. This is appended to the <title> tag of individual pages, and used in the navigation bar as the “topmost” element.

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

A shorter “title” for HTML documentation. This is used for links in the header and in the HTML Help documentation.

Adicionado na versão 0.4.

html_baseurl
Tipo:
str
Padrão:
''

The base URL which points to the root of the HTML documentation. It is used to indicate the location of document using the Canonical Link Relation.

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'

Display line numbers using <table> tag

'inline'

Display line numbers using <span> tag

Adicionado na versão 3.2.

Alterado na versão 4.0: It defaults to 'inline'.

Obsoleto desde a versão 4.0.

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

A dictionary of values to pass into the template engine’s context for all pages. Single values can also be put in this dictionary using sphinx-build’s --html-define command-line option.

Adicionado na versão 0.5.

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, or a URL that points an image file for the logo. It is placed at the top of the sidebar; its width should therefore not exceed 200 pixels.

Adicionado na versão 0.4.1: The image file will be copied to the _static directory, but only if the file does not already exist there.

Alterado na versão 4.0: Also accepts a URL.

html_favicon
Tipo:
str
Padrão:
''

If given, this must be the name of an image file (path relative to the configuration directory) that is the favicon of the documentation, or a URL that points an image file for the favicon. Browsers use this as the icon for tabs, windows and bookmarks. It should be a 16-by-16 pixel icon in the PNG, SVG, GIF, or ICO file formats.

Exemplo:

html_favicon = 'static/favicon.png'

Adicionado na versão 0.4: The image file will be copied to the _static, but only if the file does not already exist there.

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:
[]

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.

Exemplo:

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

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

Adicionado na versão 1.8.

Alterado na versão 3.5: Support the priority attribute

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

A list of JavaScript 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/script.js'. The attributes dictionary is used for the <script> tag’s attributes.

Exemplo:

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

As a special attribute, priority can be set as an integer to load the JavaScript file at an earlier or later step. For more information, refer to Sphinx.add_js_file().

Adicionado na versão 1.8.

Alterado na versão 3.5: Support the priority attribute

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

A list of paths that contain custom static files (such as style sheets or script files). Relative paths are taken as relative to the configuration directory. They are copied to the output’s _static directory after the theme’s static files, so a file named default.css will overwrite the theme’s default.css.

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

Nota

For security reasons, dotfiles under html_static_path will not be copied. If you would like to copy them intentionally, explicitly add each file to this setting:

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

An alternative approach is to use html_extra_path, which allows copying dotfiles under the directories.

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 list of paths that contain extra files not directly related to the documentation, such as robots.txt or .htaccess. Relative paths are taken as relative to the configuration directory. They are copied to the output directory. They will overwrite any existing file of the same name.

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:
'%b %d, %Y'

If set, a ‘Last updated on:’ timestamp is inserted into the page footer using the given strftime() format. The empty string is equivalent to '%b %d, %Y' (or a locale-dependent equivalent).

Tipo:
bool
Padrão:
True

Add link anchors for each heading and description environment.

Adicionado na versão 3.5.

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

Text for link anchors for each heading and description environment. HTML entities and Unicode are allowed.

Adicionado na versão 3.5.

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

A dictionary defining custom sidebar templates, mapping document names to template names.

The keys can contain glob-style patterns, in which case all matching documents will get the specified sidebars. (A warning is emitted when a more than one glob-style pattern matches for any document.)

Each value must be a list of strings which specifies the complete list of sidebar templates to include. If all or some of the default sidebars are to be included, they must be put into this list as well.

The default sidebars (for documents that don’t match any pattern) are defined by theme itself. The builtin themes use these templates by default: 'localtoc.html', 'relations.html', 'sourcelink.html', and 'searchbox.html'.

The bundled first-party sidebar templates that can be rendered are:

  • 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'],
}

This will render the custom template windows-sidebar.html and the quick search box within the sidebar of the given document, and render the default sidebars for all other pages (except that the local TOC is replaced by the global TOC).

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: A single string value for html_sidebars will be removed.

Alterado na versão 2.0: html_sidebars must be a list of strings, and no longer accepts a single string value.

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

This will render the template custom-download.html.jinja as the page download.html.

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

If True, generate domain-specific indices in addition to the general index. For e.g. the Python domain, this is the global module index.

This value can be a Boolean or a list of index names that should be generated. To find out the index name for a specific index, look at the HTML file name. For example, the Python module index has the name 'py-modindex'.

Exemplo:

html_domain_indices = {
    'py-modindex',
}

Adicionado na versão 1.0.

Alterado na versão 7.4: Permit and prefer a set type.

html_use_index
Tipo:
bool
Padrão:
True

Controls if an index is added to the HTML documents.

Adicionado na versão 0.4.

html_split_index
Tipo:
bool
Padrão:
False

Generates two versions of the index: once as a single page with all the entries, and once as one page per starting letter.

Adicionado na versão 0.4.

html_copy_source
Tipo:
bool
Padrão:
True

If True, the reStructuredText sources are included in the HTML build as _sources/docname.

Tipo:
bool
Padrão:
True

If True (and html_copy_source is true as well), links to the reStructuredText sources will be added to the sidebar.

Adicionado na versão 0.6.

Tipo:
str
Padrão:
'.txt'

The suffix to append to source links (see html_show_sourcelink), unless files they have this suffix already.

Adicionado na versão 1.5.

html_use_opensearch
Tipo:
str
Padrão:
''

If nonempty, an OpenSearch description file will be output, and all pages will contain a <link> tag referring to it. Since OpenSearch doesn’t support relative URLs for its search page location, the value of this option must be the base URL from which these documents are served (without trailing slash), e.g. 'https://docs.python.org'.

Adicionado na versão 0.2.

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

The file name suffix (file extension) for generated HTML files.

Adicionado na versão 0.4.

Tipo:
str
Padrão:
The value of html_file_suffix

The suffix for generated links to HTML files. Intended to support more esoteric server setups.

Adicionado na versão 0.6.

Tipo:
bool
Padrão:
True

If True, “© Copyright …” is shown in the HTML footer, with the value or values from copyright.

Adicionado na versão 1.0.

html_show_search_summary
Tipo:
bool
Padrão:
True

Show a summary of the search result, i.e., the text around the keyword.

Adicionado na versão 4.5.

html_show_sphinx
Tipo:
bool
Padrão:
True

Add “Created using Sphinx” to the HTML footer.

Adicionado na versão 0.4.

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

Encoding of HTML output files. This encoding name must both be a valid Python encoding name and a valid HTML charset value.

Adicionado na versão 1.0.

html_compact_lists
Tipo:
bool
Padrão:
True

If True, a list all whose items consist of a single paragraph and/or a sub-list all whose items etc… (recursive definition) will not use the <p> element for any of its items. This is standard docutils behaviour. Default: True.

Adicionado na versão 1.0.

html_secnumber_suffix
Tipo:
str
Padrão:
'. '

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

Adicionado na versão 1.0.

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

Language to be used for generating the HTML full-text search index. This defaults to the global language selected with language. English ('en') is used as a fall-back option if there is no support for this language.

Support exists for the following languages:

  • 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

Each language (except Japanese) provides its own stemming algorithm. Sphinx uses a Python implementation by default. If you want to accelerate building the index file, you can use a third-party package (PyStemmer) by running pip install PyStemmer.

Adicionado na versão 1.1: Support English (en) and Japanese (ja).

Alterado na versão 1.3: Adicionado outros idiomas.

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

A dictionary with options for the search language support. The meaning of these options depends on the language selected. Currently, only Japanese and Chinese support options.

Japanese:
type – the type of the splitter to use.

The other options depend on the splitter used.

'sphinx.search.ja.DefaultSplitter'

The TinySegmenter algorithm, used by default.

'sphinx.search.ja.MecabSplitter':

The MeCab binding To use this splitter, the ‘mecab’ python binding or dynamic link library (‘libmecab.so’ for Linux, ‘libmecab.dll’ for Windows) is required.

'sphinx.search.ja.JanomeSplitter':

The Janome binding. To use this splitter, Janome is required.

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.

Options for 'mecab':
dic_enc:

dic_enc option é a codificação do algoritmo MeCab.

dict:

dict option é o dicionário para usar algoritmo MeCab.

lib:

lib option is the library name for finding the MeCab library via ctypes if the Python binding is not installed.

Por exemplo:

html_search_options = {
    'type': 'mecab',
    'dic_enc': 'utf-8',
    'dict': '/path/to/mecab .dic',
    'lib': '/path/to/libmecab.so',
}
Options for '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’.

Chinese:
dict

The jieba dictionary path for using a custom dictionary.

Adicionado na versão 1.1.

Alterado na versão 1.4: Allow any custom splitter in the type setting for Japanese.

html_search_scorer
Tipo:
str
Padrão:
''

The name of a JavaScript file (relative to the configuration directory) that implements a search results scorer. If empty, the default will be used.

The scorer must implement the following interface, and may optionally define the score() function for more granular control.

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.

Tipo:
bool
Padrão:
True

Link images that have been resized with a scale option (scale, width, or height) to their original full-resolution image. This will not overwrite any link given by the target option on the the image directive, if present.

Dica

To disable this feature on a per-image basis, add the no-scaled-link class to the image directive:

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

Adicionado na versão 1.3.

Alterado na versão 3.0: Images with the no-scaled-link class will not be linked.

html_math_renderer
Tipo:
str
Padrão:
'mathjax'

The maths renderer to use for HTML output. The bundled renders are mathjax and imgmath. You must also load the relevant extension in extensions.

Adicionado na versão 1.8.

Opções para saída Single HTML

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

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

A dictionary defining custom sidebar templates, mapping document names to template names.

This has the same effect as html_sidebars, but the only permitted key is 'index', and all other keys are ignored.

Opções para ajuda saída HTML

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

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

Output file base name for HTML help builder. The default is the project name with spaces removed and doc appended.

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

This is the file name suffix for generated HTML help files.

Adicionado na versão 2.0.

Tipo:
str
Padrão:
The value of htmlhelp_file_suffix

Suffix for generated links to HTML files.

Adicionado na versão 2.0.

Opções para saída Ajuda Apple

Adicionado na versão 1.3.

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

Nota

Apple Help output will only work on Mac OS X 10.6 and higher, as it requires the hiutil and codesign command-line tools, neither of which are Open Source.

You can disable the use of these tools using applehelp_disable_external_tools, but the result will not be a valid help book until the indexer is run over the .lproj directories within the bundle.

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

The basename for the Apple Help Book. The default is the project name with spaces removed.

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'

The bundle version, as a string.

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

The development region. Defaults to Apple’s recommended setting, 'en-us'.

applehelp_icon
Tipo:
str
Padrão:
None

Path to the help bundle icon file or None for no icon. According to Apple’s documentation, this should be a 16-by-16 pixel version of the application’s icon with a transparent background, saved as a PNG file.

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

The product tag for use with applehelp_kb_url.

applehelp_kb_url
Tipo:
str
Padrão:
None

The URL for your knowledgebase server, e.g. https://example.com/kbsearch.py?p='product'&q='query'&l='lang'. At runtime, Help Viewer will replace 'product' with the contents of applehelp_kb_product, 'query' with the text entered by the user in the search box, and 'lang' with the user’s system language.

Set this to to None to disable remote search.

applehelp_remote_url
Tipo:
str
Padrão:
None

The URL for remote content. You can place a copy of your Help Book’s Resources directory at this location and Help Viewer will attempt to use it to fetch updated content.

For example, if you set it to https://example.com/help/Foo/ and Help Viewer wants a copy of index.html for an English speaking customer, it will look at https://example.com/help/Foo/en.lproj/index.html.

Set this to to None for no remote content.

applehelp_index_anchors
Tipo:
bool
Padrão:
False

Tell the help indexer to index anchors in the generated HTML. This can be useful for jumping to a particular topic using the AHLookupAnchor function or the openHelpAnchor:inBook: method in your code. It also allows you to use help:anchor URLs; see the Apple documentation for more information on this topic.

applehelp_min_term_length
Tipo:
str
Padrão:
None

Controls the minimum term length for the help indexer. If None, use the default length.

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

Either a language specification (to use the built-in stopwords), or the path to a stopwords plist, or None if you do not want to use stopwords. The default stopwords plist can be found at /usr/share/hiutil/Stopwords.plist and contains, at time of writing, stopwords for the following languages:

  • German (de)

  • English (en)

  • Spanish (es)

  • French (fr)

  • Hungarian (hu)

  • Italian (it)

  • Swedish (sv)

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

Specifies the locale to generate help for. This is used to determine the name of the .lproj directory inside the Help Book’s Resources, and is passed to the help indexer.

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

Specifies the help book title.

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

Specifies the identity to use for code signing. Use None if code signing is not to be performed.

Defaults to the value of the CODE_SIGN_IDENTITY environment variable, which is set by Xcode for script build phases, or None if that variable is not set.

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.

Defaults to a list based on the value of the OTHER_CODE_SIGN_FLAGS environment variable, which is set by Xcode for script build phases, or the empty list if that variable is not set.

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

The path to the codesign program.

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

The path to the hiutil program.

applehelp_disable_external_tools
Tipo:
bool
Padrão:
False

Do not run the indexer or the code signing tool, no matter what other settings are specified.

This is mainly useful for testing, or where you want to run the Sphinx build on a non-macOS platform and then complete the final steps on a Mac for some reason.

Options for EPUB output

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

Nota

The actual value for some of these options is not important, but they are required for the Dublin Core metadata.

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

The basename for the EPUB file.

epub_theme
Tipo:
str
Padrão:
'epub'

The HTML theme for the EPUB output. Since the default themes are not optimised for small screen space, using the same theme for HTML and EPUB output is usually not wise. This defaults to 'epub', a theme designed to save visual space.

epub_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. The options understood by the builtin themes are described here.

Adicionado na versão 1.2.

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

The title of the document.

Alterado na versão 2.0: It defaults to the project option (previously html_title).

epub_description
Tipo:
str
Padrão:
'unknown'

The description of the document.

Adicionado na versão 1.4.

Alterado na versão 1.5: Renamed from epub3_description

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

The author of the document. This is put in the Dublin Core metadata.

epub_contributor
Tipo:
str
Padrão:
'unknown'

The name of a person, organisation, etc. that played a secondary role in the creation of the content of an EPUB Publication.

Adicionado na versão 1.4.

Alterado na versão 1.5: Renamed from epub3_contributor

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

The language of the document. This is put in the Dublin Core metadata.

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

The publisher of the document. This is put in the Dublin Core metadata. You may use any sensible string, e.g. the project homepage.

Tipo:
str
Padrão:
The value of copyright

The copyright of the document.

epub_identifier
Tipo:
str
Padrão:
'unknown'

An identifier for the document. This is put in the Dublin Core metadata. For published documents this is the ISBN number, but you can also use an alternative scheme, e.g. the project homepage.

epub_scheme
Tipo:
str
Padrão:
'unknown'

The publication scheme for the epub_identifier. This is put in the Dublin Core metadata. For published books the scheme is 'ISBN'. If you use the project homepage, 'URL' seems reasonable.

epub_uid
Tipo:
str
Padrão:
'unknown'

A unique identifier for the document. This is put in the Dublin Core metadata. You may use a XML’s Name format string. You can’t use hyphen, period, numbers as a first character.

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

The cover page information. This is a tuple containing the filenames of the cover image and the html template. The rendered html cover page is inserted as the first item in the spine in content.opf. If the template filename is empty, no html cover page is created. No cover at all is created if the tuple is empty.

Examples:

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'),
)

The default value is ().

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'

Include all ToC entries that are not hidden

'includehidden'

Include all ToC entries

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

  • 'lualatex' – LuaLaTeX

  • 'platex' – pLaTeX

  • 'uplatex' – upLaTeX (default if language is 'ja')

Cuidado

'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 to 'pdflatex' in Latin language document of occasional Cyrillic or Greek letters or words. This is not automatic, see the discussion of the 'fontenc' key in latex_elements .

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 latex_elements 'preamble' key). 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: Usa xelatex (e o pacote LaTeX xeCJK) por padrão para documentos chineses.

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

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

Alterado na versão 4.0: 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.

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. By default, the topmost sectioning unit is switched by documentclass: section is used if documentclass will be howto, otherwise chapter is used be used.

Note that if LaTeX uses \part command, then the numbering of sectioning units one level deep gets off-sync with HTML numbering, because LaTeX numbers \chapter continuously (or \section for howto).

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

If True, generate domain-specific indices in addition to the general index. For e.g. the Python domain, this is the global module index.

This value can be a Boolean or a list of index names that should be generated. To find out the index name for a specific index, look at the HTML file name. For example, the Python module index has the name 'py-modindex'.

Exemplo:

latex_domain_indices = {
    'py-modindex',
}

Adicionado na versão 1.0.

Alterado na versão 7.4: Permit and prefer a set type.

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.

Each table can override the global style via :class: option, or .. rst-class:: for no-directive tables (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 . This 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.

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 with 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, e.g. if they are referenced in custom LaTeX added in latex_elements. Image files that are referenced in source files (e.g. via .. image::) are copied automatically.

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

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

If True, generate domain-specific indices in addition to the general index. For e.g. the Python domain, this is the global module index.

This value can be a Boolean or a list of index names that should be generated. To find out the index name for a specific index, look at the HTML file name. For example, the Python module index has the name 'py-modindex'.

Exemplo:

texinfo_domain_indices = {
    'py-modindex',
}

Adicionado na versão 1.1.

Alterado na versão 7.4: Permit and prefer a set type.

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:
{}

A dictionary of options that influence the look and feel of the selected theme. These are theme-specific. The options understood by the builtin themes are described here.

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:
True

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

Atenção

O valor padrão para esta opção será alterado no Sphinx 8.0; a partir dessa versão, as respostas HTTP 401 aos hiperlinks verificados serão tratadas como “broken” por padrão.

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:
True

When an HTTP response is not received from a webserver before the configured linkcheck_timeout expires, the current default behaviour of the linkcheck builder is to treat the link as ‘broken’. To report timeouts using a distinct report code of timeout, set linkcheck_report_timeouts_as_broken to False.

Atenção

A partir do Sphinx 8.0, os tempos limite que ocorrem durante a verificação de hiperlinks serão relatados usando o novo código de status ‘timeout’.

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.

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

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.

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

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.

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

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.

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

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