Configuração¶
O diretório de configuração deve conter um arquivo chamado conf.py
. Esse arquivo (contendo código Python) é chamado “arquivo de configuração da construção” e (geralmente) contém toda configuração necessária para personalizar o comportamento das entradas e saídas do Sphinx.
Um arquivo opcional docutils.conf pode ser adicionado ao diretório de configuração para ajustar a configuração do Docutils se não for substituído ou definido pelo Sphinx.
O arquivo de configuração é executado com código Python em tempo de construção (usando importlib.import_module()
, e com o diretório corrente sendo definico como diretório base) e suporta a execução arbitrária de códigos complexos. Sphinx então faz a leitura de simples nomes de arquivos do namespace como sua configuração.
Pontos importantes a notar:
Se não documentado de outra maneira, valores devem ser strings e seus conteúdos padrão são strings vazias.
O termo “nome totalmente qualificado” refere-se a uma string que nomeia um objeto Python importável dentro de um módulo; por exemplo:, o
"sphinx.builders.Builder"
quer dizer a classeBuilder
no módulosphinx.builders
.Lembrar que o nome do documento usa
/
como separador do caminho e não contém o nome da extensão do arquivo.Já que
conf.py
é lido como um arquivo Python, as regras usuais se aplicam para codificação e suporte Unicode.O conteúdo do namespace config é obtido (é assim que Sphinx pode encontrar modificações externas da configuração), portando não pode conter valores impossíveis de interpretação – remova esses no namespace com o comando
del
conforme apropriado. Módulos são removidos automaticamente, portanto não precisa usardel
após uso em seus comandos import.
Informação do Projeto¶
- project¶
Documentar nome do Projeto.
- author¶
O nome do autor(es) do documento. O padrão é
'unknown'
.
- copyright¶
Informação de direito autoral no estilo
'2008, Author Name'
.Alterado na versão 7.1: The value may now be a sequence of copyright statements in the above form, which will be displayed each to their own line.
- version¶
Versão abrangente, usada em lugar de
|version|
. Por exemplo na documentação Python, pode ser algo como2.6
.
Configuração Geral¶
- extensions¶
Uma lista de strings que são nomes de módulos de extensões. Essas podem ser extensões nativas do Sphinx (chamadas
sphinx.ext.*
) e outras configuradas.Notar que
sys.path
pode ser extendidodentro do arquivo conf se suas extensões estão em outro diretório – mas confirme o caminho real. Se o caminho de sua extensão é relativo ao diretório de configuração, usaros.path.abspath()
como:import sys, os sys.path.append(os.path.abspath('sphinxext')) extensions = ['extname']
Dessa maneira, pode ser carregada a extensão chamada
extname
do subdiretóriosphinxext
.O próprio arquivo de configuração pode ser uma extensão; para isso é necessário usar a função
setup()
no arquivo.
- source_suffix¶
A extensão de arquivos fonte. Sphinx considera os arquivos com estes sufixos como fonte. O valor pode ser um dicionário mapeando extensões de arquivos para tipos de arquivos. Por exemplo:
source_suffix = { '.rst': 'restructuredtext', '.txt': 'restructuredtext', '.md': 'markdown', }
Por padrão, Sphinx somente tem suporte a tipos de arquivo
'restructuredtext'
. Pode adicionar um novo tipo de fonte nas extensões permitidas. Leia a documentação da extensão para conhecer o tipo de arquivo que a extensão tem suporte.O valor também pode ser uma lista de extensões de arquivo: então o Sphinx irá considerar que todos eles mapeiam para o tipo de arquivo
'restructuredtext'
.O padrão é
{'.rst': 'restructuredtext'}
.Nota
extensões de arquivo devem começar com um ponto (por exemplo,
.rst
).Alterado na versão 1.3: Pode agora ser uma lista de extensões.
Alterado na versão 1.8: Suporte a tipo de arquivo
- source_encoding¶
A codificação de todos arquivos fonte reST. O código recomendado e valor padrão é
'utf-8-sig'
.Novo na versão 0.5: Anteriormente, Sphinx aceitava somente fontes UTF-8.
- source_parsers¶
Se informado o dicionário de classes passadas para diferentes sufixos de fontes. As chaves são sufixos, os valores podem ser uma classe ou uma string informando o nome completamente qualificado da classe informada. A classe passada pode ser
docutils.parsers.Parser
ousphinx.parsers.Parser
. Arquivos com sufixos que não estão no dicionário serão tratados como reStructuredText padrão.Por exemplo:
source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
Nota
Consulte Markdown para mais informações sobre o uso do Markdown com o Sphinx.
Novo na versão 1.3.
Obsoleto desde a versão 1.8: Agora o Sphinx fornece um método API
Sphinx.add_source_parser()
para registrar analisador de fonte. Use esse método.
- root_doc¶
O nome de documento do documento “root”, isto é, o documento que contém a diretiva raiz
toctree
. O padrão é'index'
.Alterado na versão 2.0: O padrão foi alterado para
'index'
de'contents'
.Alterado na versão 4.0: Renomeado
root_doc
demaster_doc
.
- exclude_patterns¶
A list of glob-style patterns [1] that should be excluded when looking for source files. They are matched against the source file names relative to the source directory, using slashes as directory separators on all platforms.
Padrões de exemplo:
'library/xml.rst'
– ignores thelibrary/xml.rst
file'library/xml'
– ignora o diretório delibrary/xml
'library/xml*'
– ignora todos os arquivos e diretórios iniciando comlibrary/xml
'**/.svn'
– ignora todos diretórios.svn
exclude_patterns
também é consultado quando buscando por arquivos estáticos nohtml_static_path
ehtml_extra_path
.Novo na versão 1.0.
- include_patterns¶
A list of glob-style patterns [1] that are used to find source files. They are matched against the source file names relative to the source directory, using slashes as directory separators on all platforms. The default is
**
, meaning that all files are recursively included from the source directory.Padrões de exemplo:
'**'
– all files in the source directory and subdirectories, recursively'library/xml'
– just thelibrary/xml
directory'library/xml*'
– all files and directories starting withlibrary/xml
'**/doc'
– alldoc
directories (this might be useful if documentation is co-located with source files)
Novo na versão 5.1.
- templates_path¶
A lista de caminhos que contêm modelos extras (ou modelos que sobrepõe temas internos ou específicos do tema). Caminhos relativos são tratados como relativos ao diretório da configuração.
Alterado na versão 1.3: Como esses arquivos não devem ser construídos, são automaticamente adicionados em
exclude_patterns
.
- template_bridge¶
String com nome totalmente qualificado de chamável (ou simplesmente uma classe) que retorna uma instância de
TemplateBridge
. Essa instância é então usada para renderizar a criação de documentos HTML ou de outros construtores (construtor corrente). (Note que a ligação do modelo do tema deve comportar HTML se temas são usados.)
- rst_epilog¶
Uma string de reStructuredText que pode ser incluída ao final de todo fonte que for lido. Isso é possível adicionar uma substituição que estará disponível em todo arquivo (outro como
rst_prolog
). Exemplo:rst_epilog = """ .. |psf| replace:: Python Software Foundation """
Novo na versão 0.6.
- rst_prolog¶
Uma string de reStructuredText que será incluída no início de cada arquivo fonte que é lido. Este é um local possível para adicionar substituições que devem estar disponíveis em todos os arquivos (outro sendo
rst_epilog
). Um exemplo:rst_prolog = """ .. |psf| replace:: Python Software Foundation """
Novo na versão 1.0.
- primary_domain¶
O nome do domínio padrão. Também pode ser
None
para desabilitar um domínio padrão. O padrão é'py'
. Esses objetos em outros domínios (se o nome do domínio é fornecido explicitamente ou selecionado por uma diretivadefault-domain
) terão o nome do domínio explicitamente prefixado quando nomeado (por exemplo, quando o domínio padrão é C, funções Python serão nomeadas “função Python”, não apenas “função”).Novo na versão 1.0.
- default_role¶
O nome de uma regra reST (nativa ou extensão Sphinx) para usar role padrão, isso é, o texto marcado
`como esse`
. Pode ser configurado para'py:obj'
para referência cruzada do`filtro`
. O padrão éNone
que não reassinala a role padrão.The default role can always be set within individual documents using the standard reST default-role directive.
Novo na versão 0.4.
- keep_warnings¶
Se true, mantém avisos como parágrafos de “mensagens de sistema” nos documentos construídos. A menos que isso seja definido, avisos são sempre exibidos na saída padrão quando
sphinx-build
for executado.O padrão é
False
, o comportamento pré-0.5 foi sempre mantê-los.Novo na versão 0.5.
- suppress_warnings¶
Uma lista arbitrária, dos tipos de mensagens de aviso que devem ser suprimidas.
Sphinx suporta os seguintes tipos de alertas:
app.add_node
app.add_directive
app.add_role
app.add_generic_role
app.add_source_parser
autosectionlabel.*
download.not_readable
epub.unknown_project_files
epub.duplicated_toc_entry
i18n.inconsistent_references
index
image.not_readable
ref.term
ref.ref
ref.numref
ref.keyword
ref.option
ref.citation
ref.footnote
ref.doc
ref.python
misc.highlighting_failure
toc.circular
toc.excluded
toc.not_readable
toc.secnum
Você pode escolher entre esses tipos. Você também pode fornecer apenas o primeiro componente para excluir todos os avisos anexados a ele.
Atualmente essa opção é considerada experimental.
Novo na versão 1.4.
Alterado na versão 1.5: Adic.
misc.highlighting_failure
Alterado na versão 1.5.1: Adic.
epub.unknown_project_files
Alterado na versão 1.6: Adic.
ref.footnote
Alterado na versão 2.1: Adicionada
autosectionlabel.*
Alterado na versão 3.3.0: Adicionada
epub.duplicated_toc_entry
Alterado na versão 4.3: Adicionado
toc.excluded
etoc.not_readable
Novo na versão 4.5:
Adicionado
i18n.inconsistent_references
Novo na versão 7.1: Added
index
warning type.
- needs_sphinx¶
Se configurado como uma string de versão
major.minor
como'1.1'
, Sphinx irá comparar isso com a sua versão e recusará construir se sua versão for muito antiga. O padrão é nenhum requerimento.Novo na versão 1.0.
Alterado na versão 1.4: também aceita string micro versão
- needs_extensions¶
O valor pode ser dicionário especificando os requerimentos das extensões
extensions
; ex:needs_extensions = {'sphinxcontrib.something': '1.5'}
. A string da versão deve ser no formatomajor.minor
. Requerimentos não precisam ser expecificado para todas extensões, apenas para as que devem ser verificadas.Isso requer extensões que especificam sua versão para o Sphinx (ver Sphinx Extensions API para como usar isso).
Novo na versão 1.3.
- manpages_url¶
Um URL para fazer referência cruzada aos papéis
manpage
. Se estiver definido parahttps://manpages.debian.org/{path}
, o papel:manpage:`man(1)`
será vinculado a <https://manpages.debian.org/man(1)>. Os padrões disponíveis são:page
- página manual (man
)section
- a seção do manual (1
)path
- a página original e a seção especificada do manual (man(1)
)
Também suporta páginas especificadas como
man.1
.Nota
Atualmente afeta somente geração HTML mas pode ser expandido no futuro.
Novo na versão 1.7.
- nitpicky¶
Se true (verdadeiro), Sphinx irá avisar sobre todas referências onde o alvo não foi encontrado. Padrão é
False
. Pode ser ativado temporáriamente usando na linha de comando com-n
.Novo na versão 1.0.
- nitpick_ignore¶
A set or list of
(type, target)
tuples (by default empty) that should be ignored when generating warnings in “nitpicky mode”. Note thattype
should include the domain name if present. Example entries would be('py:func', 'int')
or('envvar', 'LD_LIBRARY_PATH')
.Novo na versão 1.1.
Alterado na versão 6.2: Changed allowable container types to a set, list, or tuple
- nitpick_ignore_regex¶
Uma versão estendida do
nitpick_ignore
, que interpreta as stringstype
etarget
como expressões regulares. Note que a expressão regular deve corresponder a toda a string (como se os marcadores^
e$
tivessem sido inseridos.)Por exemplo,
(r'py:.*', r'foo.*bar\.B.*')
irá ignorar avisos chatos para todas as entidades python que comecem com``’foo’`` e tenham'bar.B'
neles, tal como('py:const', 'foo_package.bar.BAZ_VALUE')
ou('py:class', 'food.bar.Barman')
.Novo na versão 4.1.
Alterado na versão 6.2: Changed allowable container types to a set, list, or tuple
- numfig¶
Se verdadeiro, figuras, tabelas e bloco de códigos são automaticamente numerados, caso tenham legenda. Se a regra
numref
estivar habilitada. Abrange atualmente HTML e LaTeX. PadrãoFalse
.Nota
O construtor LaTeX sempre assinala números onde essa opção é habilitada ou não
Novo na versão 1.3.
- numfig_format¶
Um dicionário mapeando
'figure'
,'table'
,'code-block'
e'section'
para strings que são usadas para o formato de números de figura. Como um caractere especial,%s
será substituído com o número da figura.O padrão é usar
'Fig. %s'
para'figure'
,'Table %s'
para'table'
,'Listing %s'
para'code-block'
e'Section %s'
para'section'
.Novo na versão 1.3.
- numfig_secnum_depth¶
se configurado para
0
, figuras, tabelas e bloco de código são continuamente numerados iniciando em1
.se
1
(padrão) números serãox.1
,x.2
, … comx
o número da seção (nível superior de seção); emx.
se não houver secão). Isso naturalmente se aplica, somente se numeração foi ativada através da opção:numbered:
da diretivatoctree
.2
significa que números serãox.y.1
,x.y.2
, … se existirem em uma sub-seção (mas aparedcemx.1
,x.2
, … se existirem sob uma seção e1
,2
, … se não existirem em nenhuma seção nível superior.)etc.
Novo na versão 1.3.
Alterado na versão 1.7: O construtor LaTeX obedece essa configuração (se
numfig
éTrue
).
- smartquotes¶
Se verdadeiro, a `Docutils Smart Quotes transform`__, originalmente baseada em `SmartyPants`__ (limitada ao Inglês) e atualmente aplica-se para diversos idiomas, será usada para converter aspas e traços para entidades tipograficamente corretas. Padrão:
True
.Novo na versão 1.6.6: Substitui o obsoleto
html_use_smartypants
. Aplica-se por padrão para todos os construtores excetoman
etext
(versmartquotes_excludes
.)Arquivo `docutils.conf`__ localizado no diretório de configuração (ou arquivo global
~/.docutils
) é respeitado incondicionalmente se ele desativa aspas diferentes através da opção correspondente `Docutils option`__. Mas se for ativada entãosmartquotes
, não prevalece.
- smartquotes_action¶
Esta string personaliza a transformação Smart Quotes (aspas inteligentes). Veja o arquivo
smartquotes.py
no repositório Docutils para detalhes. O padrão'qDe'
educa os caracteres normais de aspas (quote)"
,'
, travessão e meia-risca (em- e en-Dashes)---
,--
, e reticências (ellipses)...
.Novo na versão 1.6.6.
- smartquotes_excludes¶
Um
dict
cujo padrão é:{'languages': ['ja'], 'builders': ['man', 'text']}
Cada entrada fornece uma condição suficiente para ignorar a configuração
smartquotes
e desativar a transformação Smart Quotes. As chaves aceitas são como acima'builders'
ou'languages'
. Os valores são listas.Nota
Atualmente, em caso de chamada do make com múltiplos alvos, o primeiro nome será o único validado nas opções
'builders'
e decidirá por todos. Também ummake text
seguido pormake html
aninhado será emitido no formatomake text O="-E"
para forçar a transmissão dos arquivos fonte, como cache que já foi transformado. De outra maneira o requerimento não se realizará no uso do sphinx-build como cache (que é o uso padrão) dos arquivos fontes submetidos para cada construtor.Dica
Uma maneira alternativa de efetivamente desativar (ou personalizar) as aspas inteligentes para um determinado construtor, por exemplo,
latex
, é usar omake
desta maneira:make latex O="-D smartquotes_action="
This can follow some
make html
with no problem, in contrast to the situation from the prior note.Novo na versão 1.6.6.
- user_agent¶
Um User-Agent de Sphinx. É usado para um cabeçalho no acesso HTTP (ex.: linkcheck, intersphinx e assim por diante). O padrão é
"Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z"
.Novo na versão 2.3.
- tls_verify¶
Se verdadeiro, Sphinx verifica certificação do servidor. Padrão
True
.Novo na versão 1.5.
- tls_cacerts¶
Caminho para certificação do arquivo do CA ou caminho para o diretório que contem os certificados. Isso permite o dicionário mapear nome do host para o caminho do certificado. O certificado é usado para verificar a certificação do servidor.
Novo na versão 1.5.
Dica
Sphinx usa requests como uma biblioteca HTTP internamente. Portanto, Sphinx consulta um arquivo de certificação no diretório apontado pela variável de ambiente
REQUESTS_CA_BUNDLE
setls_cacerts
não estiver definida.
- today¶
- today_fmt¶
esses valores determinam como o formato da data atual, usado em detrimento de
|today|
.Se configurar
today
para um valor não vazio, ele será usado.Caso contrário, horário corrente será usado no formato
time.strftime()
e o formatotoday_fmt
.
O padrão é agora
today
e umtoday_fmt
de'%b %d, %Y'
(ou se tradução estiver habilitada comlanguage
, um formato será selecionado na localidade equivalente).
- highlight_language¶
A linguagem padrão para realçar o código-fonte. O padrão é
'default'
. É semelhante ao'python3'
; é basicamente um superconjunto de'python'
, mas ele cai para'none'
sem aviso de falha.'python3'
e outras linguagens emitem aviso se falharem.O valor deve ser um nome de lexador válido do Pygments, veja :ref:`code-examples: para mais detalhes.
Novo na versão 0.5.
Alterado na versão 1.4: O padrão agora é
'default'
. Se você preferir o realce apenas de Python 2, você pode configurá-lo de volta para'python'
.
- highlight_options¶
Um dicionário que mapeia nomes de idiomas para opções para os módulos analisadores léxicos de Pygments. Estes são específicos do analisador léxico; para as opções compreendidas por cada um, consulte a documentação do Pygments.
Exemplo:
highlight_options = { 'default': {'stripall': True}, 'php': {'startinline': True}, }
Um único dicionário de opções também é permitido. Em seguida, é reconhecido como opções para o analisador léxico especificado por
highlight_language
:# configuration for the ``highlight_language`` highlight_options = {'stripall': True}
Novo na versão 1.3.
Alterado na versão 3.5: Permite configurar opções de realce para várias linguagens
- pygments_style¶
O nome do estilo usado para enfatizar código fonte com Pygments. Se não configurado usa estilo do tema ou ‘sphinx’` é selecionado na saída HTML.
Alterado na versão 0.3: Se o valor é completamente qualificado como um nome configurado de estilo de classe Pygments, então será usado como estilo personalizado.
- maximum_signature_line_length¶
If a signature’s length in characters exceeds the number set, each parameter within the signature will be displayed on an individual logical line.
When
None
(the default), there is no maximum length and the entire signature will be displayed on a single logical line.A ‘logical line’ is similar to a hard line break—builders or themes may choose to ‘soft wrap’ a single logical line, and this setting does not affect that behaviour.
Domains may provide options to suppress any hard wrapping on an individual object directive, such as seen in the C, C++, and Python domains (e.g.
py:function:single-line-parameter-list
).Novo na versão 7.1.
- add_function_parentheses¶
Booleano que decide onde parenteses são anexados a funções ou regra do texto (ex: conteúdo de
:func:`input`
) para significar que o nome é chamado. Padrão paraTrue
.
- add_module_names¶
Booleano que decide sobre nomes dos módulos serão prefixados a todos nomes object (para tipos de objetos onde “modulo” é definido), e.g. para
py:function
. Padrão éTrue
.
- toc_object_entries¶
Create table of contents entries for domain objects (e.g. functions, classes, attributes, etc.). Default is
True
.
- toc_object_entries_show_parents¶
A string that determines how domain objects (e.g. functions, classes, attributes, etc.) are displayed in their table of contents entry.
Use
domain
to allow the domain to determine the appropriate number of parents to show. For example, the Python domain would showClass.method()
andfunction()
, leaving out themodule.
level of parents. This is the default setting.Use
hide
to only show the name of the element without any parents (i.e.method()
).Use
all
to show the fully-qualified name for the object (i.e.module.Class.method()
), displaying all parents.Novo na versão 5.2.
- show_authors¶
Booleano que decide diretivas para diretório
codeauthor
esectionauthor
quanto a geração nos arquivos.
- modindex_common_prefix¶
Lista de prefixos que serão ignorados para classificação índice módulos Python (ex: se configurado
['foo.']
, entãofoo.bar
é exibido sob oB
, não noF
). Isso pode ser útil quando seu projeto tem um único pacote. Atualmente funcionada só para o construtor HTML. Padrão é[]
.Novo na versão 0.6.
- trim_footnote_reference_space¶
Espaços antes das referências de rodapé são necessários para o parser reST para reconhecer notas de rodapé, mas não tem aparência boa na saída.
Novo na versão 0.6.
- trim_doctest_flags¶
Se verdadeiro, doctest marca (comentários como
# doctest: FLAG, ...
) ao final das linhas e marcas<BLANKLINE>
são removidas para todos blocos de código exibidos em sessões interativas Python (ex.. doctests). Padrão “True”. Ver a extensãodoctest
para mais possibilidades na inclusão de doctests.Novo na versão 1.0.
Alterado na versão 1.1: Agora també remove
<BLANKLINE>
.
- strip_signature_backslash¶
O padrão é
False
. Quando a remoção da barra invertida está habilitada, então cada ocorrência de\\
em uma diretiva de domínio será alterada para\
, mesmo dentro de literais de string. Este era o comportamento antes da versão 3.0, e definir esta variável comoTrue
irá restabelecer esse comportamento.Novo na versão 3.0.
Opções para internacionalização¶
Essa opção influencia Sphinx Suporte Nativo a Idiomas. Ver documentação Internacionalização, para maiores detalhes.
- language¶
The code for the language the docs are written in. Any text automatically generated by Sphinx will be in that language. Also, Sphinx will try to substitute individual paragraphs from your documents with the translation sets obtained from
locale_dirs
. Sphinx will search language-specific figures named byfigure_language_filename
(e.g. the German version ofmyfigure.png
will bemyfigure.de.png
by default setting) and substitute them for original figures. In the LaTeX builder, a suitable language will be selected as an option for the Babel package. Default is'en'
.Novo na versão 0.5.
Alterado na versão 1.4: Suporte substituição figura
Alterado na versão 5.0.
Idiomas atualmente suportados são:
ar
– Árabebg
– Búlgarobn
– Bengalica
– Catalãocak
– Caqchiquelcs
– Czechcy
– Galêsda
– Dinamarquêsde
– Alemãoel
– Gregoen
– English (default)eo
– Esperantoes
– Espanholet
– Estonianoeu
– Bascofa
– Iranianofi
– Finlandêsfr
– Francêshe
– Hebreuhi
– Hindihi_IN
– Hindi (Índia)hr
– Croatahu
– Húngaroid
– Indonésioit
– Italianoja
– Japonêsko
– Koreanolt
– Lituanolv
– Letãomk
– Macedônionb_NO
– Norueguês Bokmalne
– Nepalêsnl
– Holandêspl
– Polonêspt
– Portuguêspt_BR
– Português do Brasilpt_PT
– Português Portugalro
– Romenoru
– Russosi
– Sinhalask
– Eslovênosl
– Eslovêniasq
– Albanêssr
– Sérviosr@latin
– Sérvio (Latim)sr_RS
– Sérvio (Cirílico)sv
– Suecota
– Tâmilte
– Telugutr
– Turcouk_UA
– Ucranianour
– Urduvi
– Vietnamitazh_CN
– Chinês Simplificadozh_TW
– Chinês Traditional
- locale_dirs¶
Novo na versão 0.5.
Diretórios nos quais a pesquisa adicional do catálogo de mensagem (ver
language
), relativos ao diretório fonte. Os diretórios desse caminho de busca será usado pelo módulo padrãogettext
.Mensagens Internas do Sphinx são recuperadas de um domínio
sphinx
; se adicionar o arquivo./locale
nessa configuração, o catálogo de mensagem (compilado no formato.po
usando o programa msgfmt) deve estar em./locale/language/LC_MESSAGES/sphinx.mo
. O domínio individual dos documentos depende degettext_compact
.O padrão é
['locales']
.Nota
A opção
-v para o comando sphinx-build
é útil para verificar se a configuração locale_dirs funciona conforme o esperado. Ele emite mensagens de depuração se o diretório do catálogo de mensagens não for encontrado.Alterado na versão 1.5: Usar diretório
locales
como valor padrão.
- gettext_allow_fuzzy_translations¶
Se verdadeiro, as mensagens “difusas” nos catálogos de mensagens são usadas para tradução. O padrão é
False
.Novo na versão 4.3.
- gettext_compact¶
Novo na versão 1.1.
Se verdadeiro, um domínio de documento texto do docname e se for o nível topo arquivo de projeto ou seu diretório base.
Se definido como string, todo o domínio de texto do documento é esta string, fazendo com que todos os documentos usem um único domínio de texto.
Por padrão, o documento
markup/code.rst
termina no domínio textomarkup
. Com esta opção ativada paraFalse
serámarkup/code
.Alterado na versão 3.3: O valor string agora é aceito.
- gettext_uuid¶
Se verdadeiro, Sphinx gerá informação uuid para rastrear versão os catálogos de mensagnes. Usado para:
Adicionar linha uid para cada msgid nos arquivos .pot.
Calcular similaridade entre novas msgids e previas salvas em antigas msgids. Esse cálculo leva algum tempo.
Se deseja acelerar o cálculo, pode usar
python-levenshtein
pacote de 3. escrito em C usando o comando pip install python-levenshtein.O padrão é
False
.Novo na versão 1.3.
- gettext_location¶
Se verdadeiro, Sphinx gera informação para tradução de mensagens em catalogos de mensagens.
O padrão é
True
.Novo na versão 1.3.
- gettext_auto_build¶
Se verdadeiro, Sphinx constrói arquivo mo (binario) para cada catálogo de mensagem.
O padrão é
True
.Novo na versão 1.3.
- gettext_additional_targets¶
Para especificar nome para habilitar gettext extraindo e traduzindo aplicando i18n adicionalmente. Pode ser especificado os nomes:
- índice:
index terms
- Literal-block:
blocos literais (anotação
::
e diretivacode-block
)- Doctest-block:
bloco doctest
- Raw:
conteúdo bruto
- imagem:
uri de imagem/figura
Por exemplo:
gettext_additional_targets = ['literal-block', 'image']
.Padrão é
[]
.Novo na versão 1.3.
Alterado na versão 4.0: O texto alternativo da imagem é traduzido por padrão.
- figure_language_filename¶
O nome do arquivo de imagem no idioma específico. O padrão é
{root}.{idioma}{ext}
. Será expandido paradiretório/arquivo.en.png
derivado de.. image:: diretório/nomearquivo.png
. Os códigos disponíveis são:{root}
- O nome do arquivo, incluindo componentes de caminho, porem sem a extensão do arquivo, ex.diretório/arquivo
{path}
- o caminho do diretório do nome do arquivo, com barra final se não for vazio, ex.diretório/
{docpath}
- o componente do caminho do diretório para o documento atual, com uma barra se não estiver vazio.{basename}
- nome do arquivo sem o caminho do diretório e sem a extensão do arquivo, ex.arquivo
{ext}
- a extensão do arquivo, ex..png
{language}
- idioma da tradução, ex.en
Por exemplo, configurado isso para
{path}{language}/{basename}{ext}
irão ser expandidas paradirname/en/filename.png
.Novo na versão 1.4.
Alterado na versão 1.5: Adic.
{path}
e{basename}
termos.Alterado na versão 3.2: Adicionado o token
{docpath}
.
- translation_progress_classes¶
Control which, if any, classes are added to indicate translation progress. This setting would likely only be used by translators of documentation, in order to quickly indicate translated and untranslated content.
True
: addtranslated
anduntranslated
classes to all nodes with translatable content.translated
: only add thetranslated
class.untranslated
: only add theuntranslated
class.False
: do not add any classes to indicate translation progress.
O padrão é
False
.Novo na versão 7.1.
Opções para Math¶
Estas opções influenciam notações Math.
- math_number_all¶
Defina essa opção para
True
se deseja exibir numeração. O padrão éFalse
.
- math_eqref_format¶
Uma string usada para formatar os rótulos das referências às equações. O marcador de posição
{number}
representa o número da equação.Exemplo:
'Eq.{number}'
é renderizado como, por exemplo,Eq.10
.
- math_numfig¶
Se
Verdadeiro
, equações matemáticas serão exibidas como numeradas através das páginas quandonumfig
estiver habilitada. A configuraçãonumfig_secnum_depth
será respeitada. Será usadaeq
, não será usadanumref
, role deve ser usada para referenciar número de equações. Padrão éVerdadeiro
.Novo na versão 1.7.
Opções para saída HTML¶
Essas opções influenciam HTML bem como Saída HTML Help e outros construtores que usam classe Sphinx HTMLWriter.
- html_theme¶
O “tema” que a saída HTML deve usar. Veja a seção sobre temas. O padrão é
'alabaster'
.Novo na versão 0.6.
- html_theme_options¶
Dicionário de opções que influenciam aparência e comportamento do tema selecionado. São específicos para tema. Para opções inteligíveis dos temas veja this section.
Novo na versão 0.6.
- html_theme_path¶
Lista de caminhs que contém temas configurados, pode ser subdiretórios ou arquivos zip. Relativo ao caminho do diretório de configuração.
Novo na versão 0.6.
- html_style¶
Folha de estilo para páginas HTML. Arquivo com esse nome deve existir no caminho
static/
, ou nos caminhos configuráveishtml_static_path
. Padrão é folha de estilo para o tema escolhido. Se desejar adicionar ou sobrepôr apenas alguns parâmetros usar CSS@import
para importar folha de estilos.
- html_title¶
O “título” para documentação HTML gerada pelos modelos Sphinx. Anexado na tag
<title>
das páginas individuais e usada na barra de navegação do elemento “superior”. Padrão para'documentação <project> v<revision> '
.
- html_short_title¶
Um “título” mais curto para os documentos HTML. Isso é usado para links no cabeçalho e nos documentos de Ajuda em HTML. Se não for fornecido, o padrão é o valor de
html_title
.Novo na versão 0.4.
- html_baseurl¶
O URL base que aponta para a raiz da documentação HTML. É usado para indicar o local do documento usando The Canonical Link Relation. Padrão:
''
.Novo na versão 1.8.
- html_codeblock_linenos_style¶
O estilo de números de linha para blocos de código.
'table'
– exibe números de linha usando a tag<table>
'inline'
– exibe números de linha usando a tag<span>
(padrão)
Novo na versão 3.2.
Alterado na versão 4.0: Tem como padrão
'inline'
.Obsoleto desde a versão 4.0.
- html_context¶
Dicionário de valores para passar ao mecanismo contexto para todas páginas. Valores simples podem ser usados nesse dicionário através da opção
-A
da linha de comando dosphinx-build
.Novo na versão 0.5.
- html_logo¶
Se fornecido, deve ser o nome de um arquivo de imagem (caminho relativo ao diretório de configuração) que é o logotipo dos documentos, ou URL que aponta um arquivo de imagem para o logotipo. Ele é colocado na parte superior da barra lateral; sua largura, portanto, não deve exceder 200 pixels. Padrão:
None
.Novo na versão 0.4.1: O arquivo de imagem será copiado para diretório
_static
da saída HTML, mas somente se o arquivo não existir nesse local.Alterado na versão 4.0: Também aceita a URL do arquivo de logotipo.
- html_favicon¶
Se fornecido, deve ser o nome de um arquivo de imagem (caminho relativo ao diretório de configuração) que é o favicon dos documentos, ou URL que aponta um arquivo de imagem para o favicon. Os navegadores modernos usam isso como ícone para abas, janelas e favoritos. Deve ser um arquivo de ícone no estilo do Windows (
.ico
), que tem 16x16 ou 32x32 pixels de tamanho. Padrão:None
.Novo na versão 0.4: O arquivo de imagem será copiado para diretório
_static
da saída HTML, mas somente se o arquivo não existir nesse local.Alterado na versão 4.0: Também aceita a URL do favicon.
- html_css_files¶
Uma lista de arquivos CSS. A entrada deve ser uma string nome de arquivo ou uma tupla contendo a string nome de arquivo e o dicionário de atributos. O nome de arquivo deve ser relativo ao
html_static_path
, ou um URI completo com esquema comohttps://example.org/style.css
. Os atributos são usados para atributos da tag<link>
. O padrão é uma lista vazia.Exemplo:
html_css_files = ['custom.css', 'https://example.com/css/custom.css', ('print.css', {'media': 'print'})]
As a special attribute, priority can be set as an integer to load the CSS file earlier or lazier step. For more information, refer
Sphinx.add_css_file()
.Novo na versão 1.8.
Alterado na versão 3.5: Suporte ao atributo de prioridade
- html_js_files¶
Uma lista de filename JavaScript. A entrada deve ser uma string filename ou uma tupla contendo a string filename e o dicionário attributes. O filename deve ser relativo ao
html_static_path
ou uma URI completa com esquema comohttps://example.org/script.js
. Os attributes são usados para atributos da tag1
. O padrão é uma lista vazia.Exemplo:
html_js_files = ['script.js', 'https://example.com/scripts/custom.js', ('custom.js', {'async': 'async'})]
As a special attribute, priority can be set as an integer to load the CSS file earlier or lazier step. For more information, refer
Sphinx.add_css_file()
.Novo na versão 1.8.
Alterado na versão 3.5: Suporte ao atributo de prioridade
- html_static_path¶
Lista de caminhos que contém arquivos estáticos (como folhas de estilo ou arquivos script). Relativos ao diretório de config. São copiados para o arquivo saída
_static
diretório após arquivos estáticos de tema, portante um arquivo chamadodefault.css
será sobreposto pelo arquivo temadefault.css
.Como esses arquivos não são destinados para serem construídos, eles são automaticamente excluídos dos arquivos fontes.
Nota
Por razões de segurança, dotfiles em
html_static_path
não serão copiados. Se desejar copiá-los intencionalmente, adicione cada caminho de arquivo a esta configuração:html_static_path = ['_static', '_static/.htaccess']
Outra forma de fazer isso, você também pode usar
html_extra_path
. Permite copiar dotfiles nos diretórios.Alterado na versão 0.4: O caminho em
html_static_path
agora pode conter subdiretórios.Alterado na versão 1.0: As entradas em
html_static_path
pode ser arquivos simples.Alterado na versão 1.8: Os arquivos em
html_static_path
são excluídos dos arquivos fonte.
- html_extra_path¶
A lista de caminhos que contem arquivos extras, não diretamente relacionados com a documentação,como
robots.txt
ou.htaccess
. Caminhos Relativos são obtidos no diretório de configuração. Serão copiados para o diretório de saida. Irão sobrepor arquivo já existente com o mesmo nome.Como esses arquivos não são destinados para serem construídos, eles são automaticamente excluídos dos arquivos fontes.
Novo na versão 1.2.
Alterado na versão 1.4: Os dotfiles no diretório extra serão copiados para o diretório de saída. E se refere am
exclude_patterns
sobre a cópia de arquivos e diretórios extras, e ignora se o caminho corresponde aos padrões.
- html_last_updated_fmt¶
If this is not None, a ‘Last updated on:’ timestamp is inserted at every page bottom, using the given
strftime()
format. The empty string is equivalent to'%b %d, %Y'
(or a locale-dependent equivalent).
- html_use_smartypants¶
Se verdadeiro, aspas e traços são convertidos para entidades tipograficamente corretas. Padrão
True
.Obsoleto desde a versão 1.6: Para desabilitar aspas smart, usar
smartquotes
.
- html_permalinks¶
Add link anchors for each heading and description environment. Default:
True
.Novo na versão 3.5.
- html_permalinks_icon¶
Text for link anchors for each heading and description environment. HTML entities and Unicode are allowed. Default: a paragraph sign;
¶
Novo na versão 3.5.
- html_sidebars¶
Modelo configurável de barra lateral, deve ser um dicionário que mapeia nomes de documentos a nomes de modelos.
As chaves podem conter padrões estilo global [1], nos casos onde os documentos que atenderem o critério, terão barras laterais especificadas. (Alerta é emitido quando mais de um padrão de estilo global combinar com um documento.)
Os valores pode ser listas ou simples strings.
O valor é uma lista, que especifica uma lista completa de modelos de barra lateral para inclusão. Se todas ou algumas barras laterais são incluídas, elas devem estar nessa lista também.
As barras laterais padrão (para documentos que não correspondem a nenhum padrão) são definidas pelo próprio tema. Os temas usam embutidos esses modelos por padrão:
['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']
.Se um valor é uma string simples, ele especifica uma barra lateral configurável a ser adicionada entre as entradas
'sourcelink.html'
e'searchbox.html'
. Isso é para compatibilidade com versões Sphinx anteriores a 1.0.
Obsoleto desde a versão 1.7: um termo simples para
html_sidebars
será removido em 2.0Modelos de barra lateral implícita são renderizados:
localtoc.html – tabela detalhada de conteúdos do documento atual
globaltoc.html – tabela esparça de conteúdo de todo o conjunto documento, modo encolhido
relations.html – links que apontam para o anterior e próximo documentos
sourcelink.html – link que aponta para o documento atual, se habilitado exibe
html_show_sourcelink
searchbox.html – caixa “pesquisa rápida”
Exemplo:
html_sidebars = { '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'], 'using/windows': ['windowssidebar.html', 'searchbox.html'], }
Renderiza modelo configurável windowssidebar.html` e caixa de pesquisa dentro da barra lateral de um dado documento e renderiza barras laterais para outras páginas (exceto a tabela local de conteúdo TOC que será substituída pela TOC global).
Novo na versão 1.0: Habilidde em usar chaves globias e especificar múltiplas barras laterais.
Notar que esse valor só não tem efeito se o tema escolhido não possuir barra lateral, como os temas scrolls e haiku.
- html_additional_pages¶
Modelos adicionais são renderizados para páginas HTML, devem ter um dicionário que mapeia nomes de documentos para nomes de modelos.
Exemplo:
html_additional_pages = { 'download': 'customdownload.html', }
Isso irá renderizar o modelo
customdownload.html
como páginadownload.html
.
- html_domain_indices¶
Se verdadeiro, gera índices específicos do domínio em adição ao índice geral. Por ex. domínio Python, é um módulo índice global. Padrão é
Verdadeiro
.Esse valor pode ser booleano ou lista de nomes de índices que devem ser gerados. Para encontrar o nome do índice para um índice específico, veja nome do arquivo HTML. Por exemplo: índice módulo Python tem nome
'py-modindex'
.Novo na versão 1.0.
- html_use_index¶
Se Verdadeiro, adiciona um índice ao documento HTML. Padrão
Verdadeiro
.Novo na versão 0.4.
- html_split_index¶
Se verdadeiro, o índice é gerado novamente: quando uma simples página com todas entradas e quando uma página por letra inicial. Padrão é
Falso
.Novo na versão 0.4.
- html_copy_source¶
Se verdadeiro, fontes reSt são incluídos no construtor HTML como
_sources/name
. O padrão éTrue
.
- html_show_sourcelink¶
Se verdadeiro (e
html_copy_source
for verdadeiro também), links para fontes reST irão aparecer na barra lateral. O padrão éTrue
.Novo na versão 0.6.
- html_sourcelink_suffix¶
Sufixo a ser anexado aos links de origem (veja
html_show_sourcelink
), a menos que eles já tenham este sufixo. O padrão é'.txt'
.Novo na versão 1.5.
- html_use_opensearch¶
Se não estiver vazio, um arquivo de descrição OpenSearch será gerado e todas as páginas conterão uma tag
<link>
referente a ele. Como o OpenSearch não oferece suporte a URLs relativos para o local da página de pesquisa, o valor dessa opção deve ser o URL base do qual esses documentos são veiculados (sem barra final), por exemplo,"https://docs.python.org"
. O padrão é''
.
- html_file_suffix¶
This is the file name suffix for generated HTML files, if set to a
str
value. If left to the defaultNone
, the suffix will be".html"
.Novo na versão 0.4.
- html_link_suffix¶
Sufixo para links gerados para arquivos HTML. O padrão é o sufixo definido em
html_file_suffix
; pode ser modificado para suportar diferentes configurações de servidores web).Novo na versão 0.6.
- html_show_copyright¶
Se verdadeiro, “(C) Copyright …” é exibido no rodapé HTML. Padrão é
True
.Novo na versão 1.0.
- html_show_search_summary¶
Se true, o texto ao redor da palavra-chave é mostrado como resumo de cada resultado da pesquisa. O padrão é
True
.Novo na versão 4.5.
- html_show_sphinx¶
Se verdadeiro, exibe “Criado usando Sphinx” no rodapé HTML. Padrão é
True
.Novo na versão 0.4.
- html_output_encoding¶
Codificação arquivos de saída HTML. Padrão é
'utf-8'
. Nota que esse nome da codificação deve ser válido no Python e noconjunto de caracteres
.Novo na versão 1.0.
- html_compact_lists¶
Se verdadeiro, uma lista com todos os itens que consistem em um único parágrafo e/ou uma sublista com todos os itens etc… (definição recursiva) não usará o elemento
<p>
para nenhum de seus itens. Este é o comportamento padrão dos docutils. Predefinição:True
.Novo na versão 1.0.
- html_secnumber_suffix¶
Sufixo para número de seções. Padrão: Default:
". "
. para suprimir o ponto final no número das seções.Novo na versão 1.0.
- html_search_language¶
Idioma usado para geração do índice HTML da pesquisa texto. Padrão ao idiomal global selecionaod com
language
. Se não houver suporte ao idioma,"en"
será usado para selecionar idioma Inglês.Atualmente suporta esses idiomas:
da
– Dinamarquêsnl
– Holandêsen
– Inglêsfi
– Finlandêsfr
– Francêsde
– Alemãohu
– Húngaroit
– Italianoja
– Japonêsno
– Norueguêspt
– Portuguêsro
– Romenoru
– Russoes
– Espanholsv
– Suecotr
– Turcozh
– Chinês
Novo na versão 1.1: Com suporte para
en
eja
.Alterado na versão 1.3: Adicionado outros idiomas.
- html_search_options¶
Um dicionário com opções de suporte a pesquisa em outros idiomas, vazio por padrão. O significado depende do idioma selecionado.
Em inglês não há opções.
Japonês suporte essas opções:
- tipo:
type is dotted module path string to specify Splitter implementation which should be derived from
sphinx.search.ja.BaseSplitter
. If not specified orNone
is specified,'sphinx.search.ja.DefaultSplitter'
will be used.Pode escolher entre esses módulos:
- ‘sphinx.search.ja.DefaultSplitter’:
Algoritmo TinySegmenter. Esse é o divisor padrão.
- ‘sphinx.search.ja.MecabSplitter’:
MeCab funcionalidade. Usar isso para dividir, ‘mecab’ ou biblioteca link dinâmico (‘libmecab.so’ para linux, ‘libmecab.dll’ para windows) é necessário.
- ‘sphinx.search.ja.JanomeSplitter’:
Associações para Janome. Para usar este divisor, Janome é exigido.
Obsoleto desde a versão 1.6:
'mecab'
,'janome'
e'default'
foram descontinuados. Para manter a compatibilidade,'mecab'
,'janome'
e'default'
também são aceitos.
Valores das outras opções dependem de fragmentar o valor escolhido.
- Opções para
'mecab'
: - dic_enc:
dic_enc option é a codificação do algoritmo MeCab.
- dict:
dict option é o dicionário para usar algoritmo MeCab.
- lib:
lib option é o nome da biblioteca para encontrar biblioteca MeCab via ctypes se o build do Python não estiver instalado.
Por exemplo:
html_search_options = { 'type': 'mecab', 'dic_enc': 'utf-8', 'dict': '/path/to/mecab.dic', 'lib': '/path/to/libmecab.so', }
- Opções para
'janome'
: - user_dic:
user_dic option é caminho para arquivo dicionário do Janome.
- user_dic_enc:
user_dic_enc option é o código de página para arquivo dicionário especificado opção
user_dic
. Padrão ‘utf8’.
Novo na versão 1.1.
Alterado na versão 1.4: opções para html_search_options idioma Japonês é reorganizado e configurações serão usados por type settings.
Chinês suporta essas opções
dict
– dicionáriojieba
caminho se deseja usar dicionário personalizado.
- html_search_scorer¶
O nome do arquivo JavaScript (relativo ao diretório de configuração) que implementa rank resultados pesquisa. Se vazio, o padrão é usado.
Novo na versão 1.2.
- html_scaled_image_link¶
If true, image itself links to the original image if it doesn’t have ‘target’ option or scale related options: ‘scale’, ‘width’, ‘height’. The default is
True
.Document authors can disable this feature manually with giving
no-scaled-link
class to the image:.. image:: sphinx.png :scale: 50% :class: no-scaled-link
Novo na versão 1.3.
Alterado na versão 3.0: Isso está desabilitado para imagens com a classe
no-scaled-link
- html_math_renderer¶
O nome da extensão math_renderer para saída HTML. O padrão é
'mathjax'
.Novo na versão 1.8.
- html_experimental_html5_writer¶
A saída é processada com o escritor HTML5. O padrão é
False
.Novo na versão 1.6.
Obsoleto desde a versão 2.0.
- html4_writer¶
A saída é processada com o escritor HTML4. O padrão é
False
.
Opções para a saída Single HTML¶
- singlehtml_sidebars¶
Os modelos personalizados da barra lateral devem ser um dicionário que mapeia nomes de documentos para nomes de modelos. E só permite uma chave chamada ‘index’. Todas as outras chaves são ignoradas. Para mais informações, consulte
html_sidebars
. Por padrão, é o mesmo quehtml_sidebars
.
Opções para ajuda saída HTML¶
- htmlhelp_basename¶
Saída arquivo base chamada construtor ajuda HTML . Padrão é
'pydoc'
.
- htmlhelp_file_suffix¶
Este é o sufixo do nome do arquivo para arquivos de ajuda HTML gerados. O padrão é
".html"
.Novo na versão 2.0.
- htmlhelp_link_suffix¶
Sufixo para links gerados para arquivos HTML. O padrão é
".html"
.Novo na versão 2.0.
Opções para saída Ajuda Apple¶
Novo na versão 1.3.
Essas opções influenciam saída Ajuda Apple. Esse construtor deriva do construtor HTML, portanto opções também se aplicam onde apropriadas.
Nota
Saída Ajuda Apple só funciona no Mac OS X 10.6 e posterior, como requer hiutil e codesign na linha de comando, ambos não são Open Source.
Pode desabilitar essa funcionalidade usando applehelp_disable_external_tools
, mas o resultado só será válido quando o indexador for executado nas pastas .lproj
.
- applehelp_bundle_id¶
O ID do Conjunto para livro de ajuda itens.
Aviso
Esse valor deve ser configurado para gerar Ajuda Apple.
- applehelp_dev_region¶
O região padrão desenv. Padrão para
'en-us'
, que é a recomentdação Apple.
- applehelp_bundle_version¶
Versão do Conjunto (como string). Padrão para
'1'
.
- applehelp_icon¶
O arquivo de ícone do pacote de ajuda ou
None
para nenhum ícone. De acordo com a documentação da Apple, esta deve ser uma versão de 16x16 pixels do ícone do aplicativo com um fundo transparente, salvo como um arquivo PNG.
- applehelp_kb_product¶
Etiqueta produto usado
applehelp_kb_url
. Padrão para'<project>-<release>'
.
- applehelp_kb_url¶
O URL de seu servidor de base de conhecimento, por exemplo,
https://example.com/kbsearch.py?p='product'&q='query'&l='lang'
. O Visualizador de Ajuda irá substituir os valores'product'
,'query'
e'lang'
em tempo de execução pelo conteúdo deapplehelp_kb_product
, o texto inserido pelo usuário no caixa de pesquisa e o idioma do sistema do usuário, respectivamente.Padrão para
None
para pesquisa remota.
- applehelp_remote_url¶
O URL para conteúdo remoto. Você pode colocar uma cópia da pasta
Resources
de seu Livro de Ajuda neste local e o Visualizador de Ajuda tentará usá-la para buscar conteúdo atualizado.ex.. se configurar
https://example.com/help/Foo/
e Visualizador Help utiliza uma cópia deindex.html
para idioma Inglês, irá parecer comhttps://example.com/help/Foo/en.lproj/index.html
.Padrão
None
para nenhum conteúdo remoto.
- applehelp_index_anchors¶
Se
True
, informa ao indexador help para ancorar índices gerados em HTML. Pode ser útil na hora de navegar para um tópico em particular usando funçãoAHLookupAnchor
openHelpAnchor:inBook:
em seu código. Também possibilita uso de URLshelp:anchor
; ver documentação Apple para maiores informações sobre esse tópico.
- applehelp_min_term_length¶
Controla o tamanho mínimo para indexador help. Padrão para
None
, o que significa que o padrão será usado.
- applehelp_stopwords¶
Especificação do idioma (usado para palavras-chave), ou o caminho para plist de palavras-chave ou
None
caso não desejar palavras-chave. A plist padrão de palavras-chave pode ser encontrada em/usr/share/hiutil/Stopwords.plist
e contém, em tempo de geração, stopwords para os idiomas:Idioma
Código
Inglês
en
Alemão
de
Espanhol
es
Francês
fr
Sueco
sv
Húngaro
hu
Italian
it
Defaults to
language
, or if that is not set, to'en'
.
- applehelp_locale¶
Especifíca para qual locale será gerado o Help. Isso é usado para determinar o nome da pasta
.lproj
dento do HelpResources
, e é passado ao indexador de ajuda.Defaults to
language
, or if that is not set, to'en'
.
- applehelp_title¶
Especifica o título do livro de jelp. Padrão para
'<project> Help'
.
- applehelp_codesign_identity¶
Especifica a identidade do código de assinatura do usuário ou
None
se a assinatura não deve ser efetuada.Padrão para o valor da variável de ambiente
CODE_SIGN_IDENTITY
, na qual Xcode constrói as fases, ouNone
se a variável não deve ser configurada.
- applehelp_codesign_flags¶
Uma lista argumentos adicionais para passar ao codesign quando assinando o livro de help.
Padrão para lista baseada nos valores das variáveis do ambiente
OTHER_CODE_SIGN_FLAGS
, as quais pode ser usadas na construção pelo Xcode ou lista vazia se a variável não for configurada.
- applehelp_indexer_path¶
O caminho para o programa hiutil. Padrão para
'/usr/bin/hiutil'
.
- applehelp_codesign_path¶
O caminho para o programa codesign. Padrão
'/usr/bin/codesign'
.
- applehelp_disable_external_tools¶
Se
True
, o construtor não irá executar o indexador ou a ferramente de assinatura, não importa o que outras configurações especificam.Essa é a parte mais útil para teste, onde pode ser solicitado para o Sphinx ser construído em uma plataforma não MAC OS X e então completar apenas os passos finais no OS X.
O padrão é
False
.
Opções para saída epub¶
Essas opções influenciam a saída do epub. Como esse construtor deriva do construtor HTML, as opções HTML também se aplicam quando apropriado. Os valores reais para algumas das opções não são realmente importantes, eles apenas têm que ser inseridos nos metadados Dublin Core.
- epub_theme¶
O tema HTML para saída epub. Desde que temas padrões não são otimizados para dispositivos telas menores, usando os mesmos temas HTML a saída epub não será adequada. Valor padrão para tema
'epub'
, é um tema para economizar espaço.
- epub_theme_options¶
Dicionário de opções que influenciam aparência e comportamento do tema selecionado. São específicos para tema. Para opções inteligíveis dos temas veja this section.
Novo na versão 1.2.
- epub_title¶
O título do documento. O padrão é a opção
html_title
, mas pode ser definido independentemente para a criação do epub. O padrão é a opçãoproject
.Alterado na versão 2.0: Usa como padrão a opção
project
.
- epub_description¶
A descrição do documento. O padrão é
'unknown'
.Novo na versão 1.4.
Alterado na versão 1.5: Renomeado a partir de
epub3_description
- epub_contributor¶
O nome da pessoa, organização, etc. que desempenha papel secundário na criação de conteúdo na publicação EPUB. O padrão é
'desconhecido'
.Novo na versão 1.4.
Alterado na versão 1.5: Renomeado a partir de
epub3_contributor
- epub_language¶
O idioma do documento. Isso será gravado nos metadados Dublin Core. O padrão é opção confval:language ou
'en'
se não for configurado.
- epub_publisher¶
O editor do documento. Isso é colocado nos metadados Dublin Core. Você pode usar qualquer string sensível, por exemplo, a página inicial do projeto. O padrão é a opção
author
.
- epub_copyright¶
Copyright do documento. Padrão para valor da opção
copyright
mas pode ser independentemente configurada para criação epub.
- epub_identifier¶
Identificador para o documento. Isso é gravado nos metadados Dublin Core. Para publicação documentos é o número ISBN, mas pode ser usado um schema alternativo, ex.. nome página do projeto. O padrão é
'unknown'
.
- epub_scheme¶
Esquema para
epub_identifier
. Gravado nos metadados do Dublin Core. Para editores o esquema é'ISBN'
. Se usar página web,'URL'
pode atender. O valor padrão é'unknown'
.
- epub_uid¶
Um identificador exclusivo para o documento. Isso é colocado nos metadados Dublin Core. Você pode usar uma string de formato de Name do XML. Você não pode usar hífen, ponto, números como um primeiro caractere. O valor padrão é
'unknown'
.
- epub_cover¶
Informação página abertura. Esse par contendo nome de arquivo da imagem do modelo html. A renderização da página será inserida como primeiro item do
content.opf
. Se o nome do modelo estiver vazio, nenhuma página abertura será criada. Nada será criado se o par estiver vazio. Exemplos:epub_cover = ('_static/cover.png', 'epub-cover.html') epub_cover = ('_static/cover.png', '') epub_cover = ()
O valor padrão é
()
.Novo na versão 1.1.
- epub_css_files¶
Uma lista de arquivos CSS. A entrada deve ser uma string filename ou uma tupla contendo a string filename e o dicionário de attributes. Para mais informações, veja
html_css_files
.Novo na versão 1.8.
- epub_guide¶
Dados Meta para elementos guia do arquivo
content.opf
. Essa é a sequência de pares contendo type, e uri e o title da informação opcional de guia. Ver documentação OPF em http://idpf.org/epub para mais detalhes. Se possível, entradas padrões para tipos cover e toc são automaticamente inseridas. Contudo os tipos podem ser explicitamente sobrepostos se as entradas forem inapropriadas. Exemplo:epub_guide = (('cover', 'cover.html', 'Cover Page'),)
O valor padrão é
()
.
- epub_pre_files¶
Arquivo adicional deve ser inserido antes do texto gerado pelo Sphinx. Lista de pares contendo nome de arquivo e título. Se título está vazio, nenhuma entrada é adicionada para o arquivo
toc.ncx
. Exemplo:epub_pre_files = [ ('index.html', 'Welcome'), ]
O valor padrão é
[]
.
- epub_post_files¶
Arquivos adicionais que devem ser inseridos após o texto gerado pelo Sphinx. Lista de pares contendo nome do arquivo e título. Essa opção é usada para adicionar sufixo. Se o título está vazio, nenhuma entrada é adicionada para o arquivo
toc.ncx
. O padrão é[]
.
- epub_exclude_files¶
Lista de arquivos que são gerados/copiados no diretório de construção mas não devem ser incluídos no arquivo epub. O padrão é
[]
.
- epub_tocdepth¶
A profundidade da tabela de conteúdos do arquivo
toc.ncs
. Deve ser um inteiro maior que zero. O padrão é 3. Nota: Estruturas mais abrangentes de tabela de conteúdos pode ser difícil para navegar.
- epub_tocdup¶
Esse indicador determina se a entrada toc será inserida novamente no início da toc subordinada. Isso permite navegação mais fácil no topo do capítulo, mas pode ser confuso por misturar diversos níveis de hierárquia na lista. O padrão do valor é
True
.
- epub_tocscope¶
Controla o escopo da tabela de conteúdos para epub. A configuração pode ter os seguintes valores:
'default'
– inclui todas entradas toc não omitidas (padrão)'includehidden'
– inclui todas entras toc
Novo na versão 1.2.
- epub_fix_images¶
Este sinalizador determina se o sphinx deve tentar corrigir formatos de imagem que não são suportados por alguns leitores epub. No momento, as imagens da paleta com uma pequena tabela de cores são atualizadas. Você precisa de Pillow, a Python Image Library, instalada para usar esta opção. O valor padrão é
False
porque a conversão automática pode perder informações.Novo na versão 1.2.
- epub_max_image_width¶
Essa opção especifíca largura máxima para imagens. Se valor for maior que zero, images com largura maior que o valor informado serão convertidas. Se valor for zero, nenhuma conversão será executada. valor padrão é
0
. Python Image Library (Pillow) deve estar disponível para usar essa opção.Novo na versão 1.2.
- epub_show_urls¶
Controle exibição endereços URL. Útil para leitores que não possuem outras maneiras de exibir URL ligadas. A configuração pode ter os seguintes valores:
'inline'
– exibir URLs dentro de parênteses (padrão)'footnote'
– exibir urls nas notas de rodapé.'no'
– não exibir URLs
Para exibir URLs vinculadas utilizar adição de regras CSS para classe
link-target
.Novo na versão 1.2.
- epub_use_index¶
Se verdadeiro, adiciona índice documento epub. Padrão para usar
html_use_index
opção pode ser configurada independentemente para criação epub.Novo na versão 1.2.
- epub_writing_mode¶
Especifica a direção da escrita. Pode ser
'horizontal'
(padrão) ou'vertical'
epub_writing_mode
'horizontal'
'vertical'
writing-mode [2]
horizontal-tb
vertical-rl
progressão página
esquerda para direita
direita para esquerda
Suporte Rolagem do Tema iBook’s
scroll-axis é vertical.
scroll-axis é horizontal.
Opções para saída LaTeX¶
Essas opções influenciam a saída do LaTeX.
- latex_engine¶
O mecanismo LaTeX para construir documentos. A configuração pode ter os valores:
'pdflatex'
– PDFLaTeX (padrão)'xelatex'
– XeLaTeX'lualatex'
– LuaLaTeX'platex'
– pLaTeX'uplatex'
– upLaTeX (padrão selanguage
for'ja'
)
Suporte do
'pdflatex'
para caracteres Unicode é limitado.Nota
2.0 adiciona suporte a
'pdflatex'
em documentos de língua latina de letras ou palavras cirílicas ou gregas ocasionais. Isto não é automático, veja a discussão sobre a chave'fontenc'
delatex_elements
.Se o seu projeto usa caracteres Unicode, definir o mecanismo para
'xelatex'
ou'lualatex'
e certificar-se de usar uma fonte OpenType com ampla cobertura de glifos é frequentemente mais fácil do que tentar fazer'pdflatex'
funcionar com os caracteres Unicode extras. Desde o Sphinx 2.0, o padrão é o GNU FreeFont que cobre bem o latim, cirílico e grego.Alterado na versão 2.1.0: Usa
xelatex
(e o pacote LaTeXxeCJK
) por padrão para documentos chineses.Alterado na versão 2.2.1: Usa
xelatex
por padrão para documentos gregos.Alterado na versão 2.3: Adiciona suporte a
uplatex
.Alterado na versão 4.0:
uplatex
se torna a configuração padrão de documentos japoneses.Ao contrário da renderização matemática de MathJaX na saída HTML, o LaTeX requer alguma configuração extra para oferecer suporte a literais Unicode em
math
: a única solução abrangente (até onde sabemos) é usar'xelatex'
ou'lualatex'
e para adicionarr'\usepackage{unicode-math}'
(por exemplo, através da chave'preamble'
delatex_elements
) Você pode preferirr'\usepackage[math-style=literal]{unicode-math}'
para manter um Unicode literal comoα
(U+03B1) por exemplo como está na saída, em vez de sendo renderizado como \(\alpha\).
- latex_documents¶
Este valor determina como agrupar a árvore de documentos em arquivos fonte LaTeX. Deve ser uma lista de tuplas
(startdocname, targetname, title, author, theme, toctree_only)
, onde os itens são:- startdocname
String que especifica o nome do documento do documento mestre do arquivo LaTeX. Todos os documentos referenciados pelo documento startdoc nas árvores TOC serão incluídos no arquivo LaTeX. (Se você deseja usar o documento raiz padrão para sua construção LaTeX, forneça seu
root_doc
aqui.)- targetname
Nome de arquivo do arquivo LaTeX no diretório de saída.
- title
Título do documento LaTeX. Pode estar vazio para usar o título do documento startdoc. Isso é inserido como marcação LaTeX, portanto, caracteres especiais como uma barra invertida ou “e” comercial devem ser representados pelos comandos LaTeX apropriados se forem inseridos literalmente.
- author
Autor do documento LaTeX. A mesma advertência de marcação LaTeX que para title se aplica. Use
\\and
para separar vários autores, como em:'John \\and Sarah'
(as barras invertidas devem ter escape do Python para chegar ao LaTeX).- theme
Tema LaTeX. Veja
latex_theme
.- toctree_only
Deve ser
True
ouFalse
. Se verdadeiro, o próprio documento startdoc não é incluído na saída, apenas os documentos referenciados por ele por meio de árvores TOC. Com esta opção, você pode colocar coisas extras no documento mestre que aparecem no HTML, mas não na saída LaTeX.
Novo na versão 1.2: Anteriormente incluindo classe do seu próprio documento podia ser prefixado a nome da classe com a string “sphinx”. Não é mais necessário.
Novo na versão 0.3: O sexto item de
toctree_only
. Pares com 5 itens são aceitos.
- latex_logo¶
Se informado deve ser o nome de um arquivo de imagem (relativo ao diretório de configuração) que será o logo dos docs. Será colocado no topo do título da página. Padrão
None
.
- latex_toplevel_sectioning¶
Este valor determina a unidade de corte superior. Deve ser escolhido entre
'part'
,'chapter'
ou'section'
. O padrão éNone
; a unidade de seção mais alta é trocada por documentclass:section
é usado se documentclass forhowto
, caso contrário,chapter
será usado.Observe que se o LaTeX usa o comando
\part
, então a numeração das unidades de seção em um nível de profundidade fica fora de sincronia com a numeração HTML, porque os números LaTeX continuamente\chapter
(ou\section
parahowto
.)Novo na versão 1.4.
- latex_appendices¶
Lista de nomes de documentos que serão anexados para todos manuais.
- latex_domain_indices¶
Se verdadeiro, gera índices específicos do domínio em adição ao índice geral. Por ex. domínio Python, é um módulo índice global. Padrão é
Verdadeiro
.Esse valor pode ser booleano ou lista de nomes de índices que devem ser gerados, para
html_domain_indices
.Novo na versão 1.0.
- latex_show_pagerefs¶
Se verdadeiro, adiciona página após referências internas. Isso é útil para cópias impressas do manual. Padrão é
False
.Novo na versão 1.0.
- latex_show_urls¶
Controle exibição endereços URL. É util para imprimir copias do manual. A configuração deve ter os seguintes valores:
'no'
– não exibir URLs (padrão)'footnote'
– exibir urls nas notas de rodapé.'inline'
– exibir URLs inline em parenteses
Novo na versão 1.0.
Alterado na versão 1.1: O valor é uma string; anteriormente era um valor boleano e valor verdadeiro selecionado exibir
'inline'
. Por compatibilidade anterior,True
ainda é aceito.
- latex_use_latex_multicolumn¶
O padrão é
False
: significa que as próprias macros do Sphinx são usadas para células mescladas de tabelas de grade. Eles permitem conteúdos gerais (blocos literais, listas, blocos de citação, …) mas podem ter problemas se a diretivatabularcolumns
foi usada para injetar marcação LaTeX do tipo>{..}
,<{..}
,@{..}
como especificação de coluna.Definir como
True
significa usar o padrão do LaTeX\multicolumn
; isso é incompatível com blocos literais na célula mesclada horizontalmente e também com vários parágrafos em tal célula se a tabela for renderizada usandotabulary
.Novo na versão 1.6.
- latex_table_style¶
A list of styling classes (strings). Currently supported:
'booktabs'
: no vertical lines, and only 2 or 3 horizontal lines (the latter if there is a header), using the booktabs package.'borderless'
: no lines whatsoever.'colorrows'
: the table rows are rendered with alternating background colours. The interface to customize them is via dedicated keys of The sphinxsetup configuration setting.Importante
With the
'colorrows'
style, the\rowcolors
LaTeX command becomes a no-op (this command has limitations and has never correctly supported all types of tables Sphinx produces in LaTeX). Please update your project to use instead the latex table color configuration keys.
Default:
['booktabs', 'colorrows']
Novo na versão 5.3.0.
Alterado na versão 6.0.0: Modify default from
[]
to['booktabs', 'colorrows']
.Each table can override the global style via
:class:
option, or.. rst-class::
for no-directive tables (cf. Tabelas). Currently recognized classes arebooktabs
,borderless
,standard
,colorrows
,nocolorrows
. The latter two can be combined with any of the first three. Thestandard
class produces tables with both horizontal and vertical lines (as has been the default so far with Sphinx).A single-row multi-column merged cell will obey the row colour, if it is set. See also
TableMergeColor{Header,Odd,Even}
in the The sphinxsetup configuration setting section.Nota
It is hard-coded in LaTeX that a single cell will obey the row colour even if there is a column colour set via
\columncolor
from a column specification (seetabularcolumns
). Sphinx provides\sphinxnorowcolor
which can be used like this:>{\columncolor{blue}\sphinxnorowcolor}
in a table column specification.
Sphinx also provides
\sphinxcolorblend
which however requires the xcolor package. Here is an example:>{\sphinxcolorblend{!95!red}}
It means that in this column, the row colours will be slightly tinted by red; refer to xcolor documentation for more on the syntax of its
\blendcolors
command (a\blendcolors
in place of\sphinxcolorblend
would modify colours of the cell contents, not of the cell background colour panel…). You can find an example of usage in the APIs em Desuso section of this document in PDF format.Dica
If you want to use a special colour for the contents of the cells of a given column use
>{\noindent\color{<color>}}
, possibly in addition to the above.Multi-row merged cells, whether single column or multi-column currently ignore any set column, row, or cell colour.
It is possible for a simple cell to set a custom colour via the raw directive and the
\cellcolor
LaTeX command used anywhere in the cell contents. This currently is without effect in a merged cell, whatever its kind.
Dica
In a document not using
'booktabs'
globally, it is possible to style an individual table via thebooktabs
class, but it will be necessary to addr'\usepackage{booktabs}'
to the LaTeX preamble.On the other hand one can use
colorrows
class for individual tables with no extra package (as Sphinx since 5.3.0 always loads colortbl).
- latex_use_xindy¶
Se for
True
, o PDF compilado a partir dos arquivos LaTeX criados pelo Sphinx usará xindy (doc__) em vez de makeindex para preparar o índice de termos gerais (do uso deindex
). Isso significa que palavras com caracteres UTF-8 serão ordenadas corretamente paralanguage
.Esta opção é ignorada se
latex_engine
for'platex'
(documentos japoneses; mendex substitui makeindex).O padrão é
True
para'xelatex'
ou'lualatex'
como makeindex, se qualquer termo indexado começar com um caractere não ascii, cria arquivos.ind
contendo bytes inválidos para codificação UTF-8. Com'lualatex'
isso então quebra a compilação do PDF.O padrão é
False
para'pdflatex'
masTrue
é recomendado para documentos que não estejam em inglês assim que alguns termos indexados usem caracteres não ascii do script de idioma.
Sphinx adiciona à distribuição de base xindy algum suporte dedicado para usar o mecanismo
'pdflatex'
com scripts cirílicos. E seja com motores'pdflatex'
ou Unicode, os documentos cirílicos lidam corretamente com a indexação de nomes latinos, mesmo com sinais diacríticos.Novo na versão 1.8.
- latex_elements¶
Novo na versão 0.5.
Sua documentação foi movida para Configuração LaTeX.
- latex_docclass¶
Dicionário mapeando
'howto'
e'manual'
para nomes reais de documentos e classes que serão usadas como classes Sphinx. Padrão é usar'article'
para'howto'
e'report'
para'manual'
.Novo na versão 1.0.
Alterado na versão 1.5: Em documentos japoneses (
language
é'ja'
), por padrão'jreport'
é usado para'howto'
e'jsbook'
para'manual'
.
- latex_additional_files¶
Lista de nome de arquivos, relativos ao diretório de configuração, para serem copiados para o diretório de construção quando gerando saída LaTeX. Isso é útil para copiar arquivos Sphinx que não são copiados automaticamente, ex: quando são referenciados por LaTeX configurável adicionados em
latex_elements
. Arquivos de Imagem que são referenciados na fonte (ex: via.. image::
) são copiados automaticamente.Confirmar que o nome de arquivo não conflita com nenhum arquivo que é copiado automaticamente.
Atenção
Filenames with extension
.tex
will automatically be handed over to the PDF build process triggered bysphinx-build -M
latexpdf
or by make latexpdf. If the file was added only to be\input{}
from a modified preamble, you must add a further suffix such as.txt
to the filename and adjust accordingly the\input{}
command added to the LaTeX document preamble.Novo na versão 0.6.
Alterado na versão 1.2: Isso sobrescreve os arquivos fornecidos pelo Sphinx, como
sphinx.sty
.
- latex_theme¶
O “tema” que a saída LaTeX deve usar. É uma coleção de configurações para a saída LaTeX (por exemplo, classe de documento, unidade de corte de nível superior e assim por diante).
Como um tema LaTeX embutido,
manual
ehowto
são empacotados.manual
Um tema LaTeX para escrever um manual. Ele importa a classe de documento
report
(documentos japoneses usamjsbook
).howto
Um tema LaTeX para escrever um artigo. Ele importa a classe de documento
article
(documentos japoneses usamjreport
).latex_appendices
está disponível apenas para este tema.
Seu padrão é
'manual'
.Novo na versão 3.0.
- latex_theme_options¶
Um dicionário de opções que influenciam a aparência do tema selecionado.
Novo na versão 3.1.
- latex_theme_path¶
Uma lista de caminhos que contêm temas LaTeX personalizados como subdiretórios. Os caminhos relativos são considerados relativos ao diretório de configuração.
Novo na versão 3.0.
Opções para saída texto¶
Essas opções influenciam a saída texto.
- text_newlines¶
Determina caracter usado como final de linha na saída texto.
'unix'
: Usa estilo para finalizar linhas (\n
)'windows'
: Usa o estilo Windows para finalizar linhas (\r\n
)'native'
: Usa o estilo de fim de linha da plataforma onde está sendo construída a documentação.
Padrão:
'unix'
.Novo na versão 1.1.
- text_sectionchars¶
String de 7 caracteres que deve ser usada para seções contidas. O primeiro caracter é usado para cabeçalhos do primeiro nível, segundo caracter para segundo nível e assim sucessivamente.
Padrão é
'*=-~"+`'
.Novo na versão 1.1.
- text_add_secnumbers¶
Booleano que decide quando os números de seção são incluídos na saída do texto. Padrão é
True
.Novo na versão 1.7.
- text_secnumber_suffix¶
Sufixo para números de seção na saída de texto. Padrão:
"."
. Defina como""
para suprimir o ponto final nos números de seção.Novo na versão 1.7.
Opções para saída página manual¶
Essas opções influenciam a saída página manual.
- man_pages¶
Esse valor determina como o grupo de páginas aparecem no manual. Deve ser uma lista de pares
(startdocname, name, description, authors, section)
, onde os itens são:- startdocname
String que especifica o nome do documento do documento mestre da página de manual. Todos os documentos referenciados pelo documento startdoc nas árvores TOC serão incluídos no arquivo de manual. (Se você deseja usar o documento raiz padrão para sua construção de páginas de manual, use seu
root_doc
aqui.)- name
Nome da página de manual. Deve ser uma string curta sem espaços ou caracteres especiais. É usado para determinar o nome do arquivo, bem como o nome da página do manual (na seção NAME).
- description
Descrição da página de manual. Isso é usado na seção NAME. Pode ser uma string vazia se você não quiser gerar automaticamente a seção NAME.
- authors
Uma lista de strings com autores ou uma única string. Pode ser uma string ou lista vazia se você não quiser gerar automaticamente uma seção AUTHORS na página de manual.
- section
A seção da página de manual. Usado para o nome do arquivo de saída, bem como no cabeçalho da página de manual.
Novo na versão 1.0.
- man_show_urls¶
Se Verdadeiro, adiciona endereços URL após links. Padrão
False
.Novo na versão 1.1.
- man_make_section_directory¶
Se verdadeiro, cria um diretório de seção na página de manual de construção. O padrão é True.
Novo na versão 3.3.
Alterado na versão 4.0: O padrão foi alterado para
False
deTrue
.Alterado na versão 4.0.2: O padrão foi alterado para
True
paraFalse
novamente.
Opções para saida TexInfo¶
Essas opções influenciam a saida Texinfo.
- texinfo_documents¶
Esse valor determina como a raiz do grupo de documento em arquivos fontes Texinfo. Devem ser uma lista de pares
(startdocname, targetname, title, author, dir_entry, description, category, toctree_only)
onde itens são:- startdocname
String que especifica o nome do documento do documento mestre do arquivo Texinfo. Todos os documentos referenciados pelo documento startdoc nas árvores TOC serão incluídos no arquivo Texinfo. (Se você deseja usar o documento mestre padrão para sua construção Texinfo, forneça seu
root_doc
aqui.)- targetname
Nome de arquivo (sem extensão) do arquivo Texinfo no diretório de saída.
- title
Título do documento Texinfo. Pode estar vazio para usar o título do documento startdoc. Inserido como marcação Texinfo, portanto, caracteres especiais como ``@ `` e ``{} `` precisarão ser escapados para serem inseridos literalmente.
- author
Autor do documento Texinfo. Inserido como marcação Texinfo. Use
@*
para separar vários autores, como em:'John@*Sarah'
.- dir_entry
O nome que vai aparecer no arquivo de menu de topo de nível
DIR
.- description
Um texto descritivo que vai aparecer no arquivo de menu de topo de nível
DIR
.- category
Especifica a seção na qual esta entrada vai aparecer no arquivo de menu de topo de nível
DIR
.- toctree_only
Deve ser
True
ouFalse
. Se verdadeiro, o próprio documento startdoc não é incluído na saída, apenas os documentos referenciados por ele por meio de árvores TOC. Com esta opção, você pode colocar coisas extras no documento mestre que aparecem no HTML, mas não na saída do Texinfo.
Novo na versão 1.1.
- texinfo_appendices¶
Lista de nomes de documentos que serão anexados para todos manuais.
Novo na versão 1.1.
- texinfo_domain_indices¶
Se verdadeiro, gera índices específicos do domínio em adição ao índice geral. Por ex. domínio Python, é um módulo índice global. Padrão é
Verdadeiro
.Esse valor pode ser booleano ou lista de nomes de índices que devem ser gerados, para
html_domain_indices
.Novo na versão 1.1.
- texinfo_show_urls¶
Controlear como exibir endereços URL.
'footnote'
– Exibir URLs nas notas de rodapé.'no'
– não exibir URLs'inline'
– exibir URLs inline em parenteses
Novo na versão 1.1.
Se verdadeiro, não gerar
@detailmenu
no “Topo” do menu contendo entradas para cada sub-menu do documento. O padrão éFalse
.Novo na versão 1.2.
- texinfo_elements¶
Um dicionário que contém TexInfo que sobrepõe aqueles que o Sphinx usualmente coloca nos arquivos gerados
.texi
.Chaves que podem ser sobrepostas são:
'paragraphindent'
Número de espaços para indentar a primeira linha de cada parágrafo, padrão
2
. Especificar0
para não haver indentação.'exampleindent'
Número de espaços para indentar as linhas de exemplo ou blocos de literais, padrão
4
. Especificar0
para não haver indentação.'preamble'
Marcação TexInfo inserida próxima do início do arquivo.
'copying'
Marcações inseridas com o bloco
Chaves que configuram outras opções e podem ser sobrepostas são:
'author'
'body'
'date'
'direntry'
'filename'
'project'
'release'
'title'
Novo na versão 1.1.
- texinfo_cross_references¶
Se false, não gera referências embutidas em um documento. Isso torna um arquivo de informação mais legível com o leitor autônomo (
info
). O padrão éTrue
.Novo na versão 4.4.
Opções para saída QtHelp¶
Essas opções influenciam a saída do qthelp. Como esse construtor deriva do construtor HTML, as opções HTML também se aplicam quando apropriado.
- qthelp_basename¶
O nome base do arquivo qthelp. O padrão é o nome
projeto
.
- qthelp_namespace¶
O namespace para o arquivo qthelp. O padrão é
org.sphinx.<project_name>.<project_version>
.
- qthelp_theme¶
Tema HTML para saída qthelp. Padrão
'nonav'
.
- qthelp_theme_options¶
Dicionário de opções que influenciam aparência e comportamento do tema selecionado. São específicos para tema. Para opções inteligíveis dos temas veja this section.
Opções para construtor linkcheck¶
- linkcheck_ignore¶
A lista de expressões regulares que combinam com as URIs que não precisam ser verificadas com o construtor linkcheck`. Exemplo:
linkcheck_ignore = [r'http://localhost:\d+/']
Novo na versão 1.1.
- linkcheck_allowed_redirects¶
Um dicionário que mapeia um padrão do URI de origem para um padrão do URI canônico. O construtor linkcheck trata o link redirecionado como “funcionando” quando:
o link no documento corresponde ao padrão de URI de origem e
o local de redirecionamento corresponde ao padrão de URI canônico.
Exemplo:
linkcheck_allowed_redirects = { # All HTTP redirections from the source URI to the canonical URI will be treated as "working". r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*' }
Se definido, o construtor linkcheck emitirá um aviso quando o redirecionamento não permitido for encontrado. É útil para detectar redirecionamentos inesperados em
o modo warn-is-error
.Novo na versão 4.1.
- linkcheck_request_headers¶
Um dicionário que mapeia baseurls para cabeçalhos de solicitação HTTP.
A chave é uma string base de URL como
"https://www.sphinx-doc.org/"
. Para especificar cabeçalhos para outros hosts,"*"
pode ser usado. Ele corresponde a todos os hosts somente quando o URL não corresponde a outras configurações.O valor é um dicionário que mapeia nome de cabeçalho para seu valor.
Exemplo:
linkcheck_request_headers = { "https://www.sphinx-doc.org/": { "Accept": "text/html", "Accept-Encoding": "utf-8", }, "*": { "Accept": "text/html,application/xhtml+xml", } }
Novo na versão 3.1.
- linkcheck_retries¶
O número de vezes que o construtor linkcheck irá tentar verificar a URL antes de assumir que está quebrada. Padrão 1 tentativa.
Novo na versão 1.4.
- linkcheck_timeout¶
Tempo para timeout, em segundos, para o construtor de verificação de links. O padrão é usar o tempo padrão do soquete Python.
Novo na versão 1.1.
- linkcheck_workers¶
O número de threads concomitantes para usar quando verificando links. Padrão 5 threads.
Novo na versão 1.1.
- linkcheck_anchors¶
Se verdadeiro, o validador do link
#anchor
. Isso requer download do documento por inteiro e é consideravelmente mais lento quando habilitado. Padrão éVerdadeiro
.Novo na versão 1.2.
- linkcheck_anchors_ignore¶
Uma lista de expressões regulares que correspondem às âncoras Sphinx deve pular ao verificar a validade das âncoras nos links. Isso permite pular âncoras que o JavaScript de um site adiciona para controlar páginas dinâmicas ou ao acionar uma solicitação REST interna. O padrão é
["^!"]
.Dica
Use
linkcheck_anchors_ignore_for_url
to check a URL, but skip verifying that the anchors exist.Nota
Se você quiser ignorar as âncoras de uma página específica ou de páginas que correspondem a um padrão específico (mas ainda verificar ocorrências das mesmas páginas que não têm âncoras), use
linkcheck_ignore
em vez disso, por exemplo como segue:linkcheck_ignore = [ 'https://www.sphinx-doc.org/en/1.7/intro.html#', ]
Novo na versão 1.5.
- linkcheck_anchors_ignore_for_url¶
A list or tuple of regular expressions matching URLs for which Sphinx should not check the validity of anchors. This allows skipping anchor checks on a per-page basis while still checking the validity of the page itself. Default is an empty tuple
()
.Novo na versão 7.1.
- linkcheck_auth¶
Passa informações de autenticação ao fazer uma construção
linkcheck
.Uma lista de tuplas
(regex_pattern, auth_info)
nas quais os itens são:- regex_pattern
Uma expressão regular que corresponde a uma URI.
- auth_info
Informações de autenticação a serem usadas para esse URI. O valor pode ser qualquer coisa que seja compreendida pela biblioteca
requests
(veja Authentication do requests para detalhes).
O construtor
linkcheck
usará o primeiro valorauth_info
correspondente que puder encontrar na listalinkcheck_auth
, então os valores anteriores na lista têm maior prioridade.Exemplo:
linkcheck_auth = [ ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')), ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)), ]
Novo na versão 2.3.
- linkcheck_rate_limit_timeout¶
O construtor
linkcheck
pode emitir um grande número de solicitações para o mesmo site em um curto período de tempo. Esta configuração controla o comportamento do construtor quando os servidores indicam que os pedidos são limitados por taxa.Se um servidor indica quando tentar novamente (usando o cabeçalho Retry-After),
linkcheck
sempre segue a indicação do servidor.Caso contrário,
linkcheck
espera um minuto antes de tentar novamente e continua dobrando o tempo de espera entre as tentativas até que tenha sucesso ou exceda olinkcheck_rate_limit_timeout
. Por padrão, o tempo limite é de 5 minutos.Novo na versão 3.4.
- linkcheck_exclude_documents¶
Uma lista de expressões regulares que correspondem a documentos nos quais o Sphinx não deve verificar a validade dos links. Isso pode ser usado para permitir o enfraquecimento do link em seções herdadas ou históricas da documentação.
Exemplo:
# ignore all links in documents located in a subfolder named 'legacy' linkcheck_exclude_documents = [r'.*/legacy/.*']
Novo na versão 4.4.
Opções para construtor XML¶
- xml_pretty¶
Se verdadeiro, impressão formatada de XML. Padrão é
Verdadeiro
.Novo na versão 1.2.
Notas de Rodapé
Anotação sobre sintaxe global disponível: podem ser usadas construções *
, ?
, [...]
e [!...]
com funcionalidade que não combinem com barras. Asterisco duplo **
pode ser usada para combinar com qualquer sequência de caracteres incluindo barras.
Opções para o domínio C¶
- c_id_attributes¶
Lista de termos que podem ser aceitos como atributos. Isso pode por exemplo ser usado como atributos
#define
são usados para portabilidade.Novo na versão 3.0.
- c_paren_attributes¶
Uma lista de strings que o analisador também deve aceitar como atributos com um argumento. Ou seja, se
my_align_as
estiver na lista, entãomy_align_as(X)
é analisado como um atributo para todas as stringsX
que têm parênteses, colchetes e chaves balanceados (ou seja,()
,[]
e{}
). Isso pode, por exemplo, ser usado quando os atributos foram definidos, com#define
, para portabilidade.Novo na versão 3.0.
- c_extra_keywords¶
Uma lista de identificadores a serem reconhecidos como palavras-chave pelo analisador C. O padrão é
['alignas', 'alignof', 'bool', 'complex', 'imaginary', 'noreturn', 'static_assert', 'thread_local']
.Novo na versão 4.0.3.
- c_maximum_signature_line_length¶
If a signature’s length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding
maximum_signature_line_length
.Novo na versão 7.1.
Opções para domínio C++¶
- cpp_index_common_prefix¶
Uma lista de prefixos que serão ignorados ao classificar objetos C++ no índice global. Por exemplo
['awesome_lib::']
.Novo na versão 1.5.
- cpp_id_attributes¶
Lista de termos que podem ser aceitos como atributos. Isso pode por exemplo ser usado como atributos
#define
são usados para portabilidade.Novo na versão 1.5.
- cpp_paren_attributes¶
Uma lista de strings que o analisador também deve aceitar como atributos com um argumento. Ou seja, se
my_align_as
estiver na lista, entãomy_align_as(X)
é analisado como um atributo para todas as stringsX
que têm parênteses, colchetes e chaves balanceados (ou seja,()
,[]
e{}
). Isso pode, por exemplo, ser usado quando os atributos foram definidos, com#define
, para portabilidade.Novo na versão 1.5.
- cpp_maximum_signature_line_length¶
If a signature’s length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding
maximum_signature_line_length
.Novo na versão 7.1.
Opções para o domínio Python¶
- python_display_short_literal_types¶
This value controls how
Literal
types are displayed. The setting is a boolean, defaultFalse
.Exemplos¶
The examples below use the following
py:function
directive:.. py:function:: serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None
When
False
,Literal
types display as per standard Python syntax, i.e.:serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None
When
True
,Literal
types display with a short, PEP 604-inspired syntax, i.e.:serve_food(item: "egg" | "spam" | "lobster thermidor") -> None
Novo na versão 6.2.
- python_use_unqualified_type_names¶
Se verdadeiro, suprime o nome do módulo da referência python se puder ser resolvido. O padrão é
False
.Novo na versão 4.0.
Nota
Esta configuração ainda está em fase experimental
- python_maximum_signature_line_length¶
If a signature’s length in characters exceeds the number set, each argument or type parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding
maximum_signature_line_length
.For the Python domain, the signature length depends on whether the type parameters or the list of arguments are being formatted. For the former, the signature length ignores the length of the arguments list; for the latter, the signature length ignores the length of the type parameters list.
For instance, with python_maximum_signature_line_length = 20, only the list of type parameters will be wrapped while the arguments list will be rendered on a single line
.. py:function:: add[T: VERY_LONG_SUPER_TYPE, U: VERY_LONG_SUPER_TYPE](a: T, b: U)
Novo na versão 7.1.
Options for the Javascript domain¶
- javascript_maximum_signature_line_length¶
If a signature’s length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding
maximum_signature_line_length
.Novo na versão 7.1.
Exemplo de arquivo configuração¶
# test documentation build configuration file, created by
# sphinx-quickstart on Sun Jun 26 00:00:43 2016.
#
# This file is executed through importlib.import_module with
# the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
#
# source_encoding = 'utf-8-sig'
# The master toctree document.
root_doc = 'index'
# General information about the project.
project = 'test'
copyright = '2016, test'
author = 'test'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = 'test'
# The full version, including alpha/beta/rc tags.
release = 'test'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#
# today = ''
#
# Else, today_fmt is used as the format for a strftime call.
#
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# These patterns also affect html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []
# The name for this set of Sphinx documents.
# "<project> v<release> documentation" by default.
#
# html_title = 'test vtest'
# A shorter title for the navigation bar. Default is the same as html_title.
#
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#
# html_logo = None
# The name of an image file (relative to this directory) to use as a favicon of
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#
# html_extra_path = []
# If not None, a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
# The empty string is equivalent to '%b %d, %Y'.
#
# html_last_updated_fmt = None
# Custom sidebar templates, maps document names to template names.
#
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#
# html_additional_pages = {}
# If false, no module index is generated.
#
# html_domain_indices = True
# If false, no index is generated.
#
# html_use_index = True
# If true, the index is split into individual pages for each letter.
#
# html_split_index = False
# If true, links to the reST sources are added to the pages.
#
# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
#
# html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change `jieba` dictionary path.
#
# html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#
# html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'testdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(root_doc, 'test.tex', 'test Documentation',
'test', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#
# latex_logo = None
# If true, show page references after internal links.
#
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
#
# latex_show_urls = False
# Documents to append as an appendix to all manuals.
#
# latex_appendices = []
# If false, no module index is generated.
#
# latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(root_doc, 'test', 'test Documentation',
[author], 1)
]
# If true, show URL addresses after external links.
#
# man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(root_doc, 'test', 'test Documentation',
author, 'test', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#
# texinfo_appendices = []
# If false, no module index is generated.
#
# texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#
# texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#
# texinfo_no_detailmenu = False
# If false, do not generate in manual @ref nodes.
#
# texinfo_cross_references = False
# -- A random example -----------------------------------------------------
import sys, os
sys.path.insert(0, os.path.abspath('.'))
exclude_patterns = ['zzz']
numfig = True
#language = 'ja'
extensions.append('sphinx.ext.todo')
extensions.append('sphinx.ext.autodoc')
#extensions.append('sphinx.ext.autosummary')
extensions.append('sphinx.ext.intersphinx')
extensions.append('sphinx.ext.mathjax')
extensions.append('sphinx.ext.viewcode')
extensions.append('sphinx.ext.graphviz')
autosummary_generate = True
html_theme = 'default'
#source_suffix = ['.rst', '.txt']