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 execfile(), e com o diretório corrente sendo definico como diretório base) e suporta a execução arbitrária de códigos complexos. Sphinx então faz a leitura de simples nomes de arquivos do namespace como sua configuração.

Pontos importantes a notar:

  • Se não documentado de outra maneira, valores devem ser strings e seus conteúdos padrão são strings vazias.

  • O termo “nome totalmente qualificado” refere-se a uma string que nomeia um objeto Python importável dentro de um módulo; por exemplo:, o "sphinx.builders.Builder" quer dizer a classe Builder no módulo sphinx.builders.

  • Lembrar que o nome do documento usa / como separador do caminho e não contém o nome da extensão do arquivo.

  • Já que conf.py é lido como um arquivo Python, as regras usuais se aplicam para codificação e suporte Unicode.

  • O conteúdo do namespace config é obtido (é assim que Sphinx pode encontrar modificações externas da configuração), portando não pode conter valores impossíveis de interpretação – remova esses no namespace com o comando del conforme apropriado. Módulos são removidos automaticamente, portanto não precisa usar del após uso em seus comandos import.

  • Existe um objeto especial chamado tags disponível no arquivo config. Pode ser usado para consultar e modificar tags (ver Incluindo conteúdo baseado em tags). Usar tags.has('tag') para consultar e tags.add('tag') e tags.remove('tag') para atualizar. Note que o construtor corrent não está disponível em conf.py, quando foi criado após o construtor ser inicializado.

Informação do Projeto

project

Documentar nome do Projeto.

author

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

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

An alias of copyright.

Novo na versão 3.5.

version

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

release

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

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

Configuração Geral

extensions

A list of strings that are module names of extensions. These can be extensions coming with Sphinx (named sphinx.ext.*) or custom ones.

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

import sys, os

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

extensions = ['extname']

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

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

source_suffix

The file extensions of source files. Sphinx considers the files with this suffix as sources. The value can be a dictionary mapping file extensions to file types. For example:

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

By default, Sphinx only supports 'restructuredtext' file type. You can add a new file type using source parser extensions. Please read a document of the extension to know which file type the extension supports.

The value may also be a list of file extensions: then Sphinx will consider that they all map to the 'restructuredtext' file type.

Default is {'.rst': 'restructuredtext'}.

Nota

file extensions have to start with a dot (e.g. .rst).

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

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

source_encoding

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

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

source_parsers

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

Por exemplo:

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

Nota

Refer to Markdown for more information on using Markdown with Sphinx.

Novo na versão 1.3.

Obsoleto desde a versão 1.8: Now Sphinx provides an API Sphinx.add_source_parser() to register a source parser. Please use it instead.

master_doc

Same as root_doc.

Alterado na versão 4.0: Renamed master_doc to root_doc.

root_doc

The document name of the “root” document, that is, the document that contains the root toctree directive. Default is 'index'.

Alterado na versão 2.0: The default is changed to 'index' from 'contents'.

Alterado na versão 4.0: Renamed root_doc from master_doc.

exclude_patterns

Uma lista de padrões estilo global que deve ser desconsiderada quando buscando arquivos fonte. 1 Eles são verificados contra arquivos fonte relativos ao diretório fonte, usando barras com separador de diretório em todas as plataformas.

Padrões de exemplo:

  • 'library/xml.rst' – ignora o arquivo library/xml.rst (substitui entrada em unused_docs)

  • 'library/xml' – ignora o diretório de library/xml

  • 'library/xml*' – ignora todos os arquivos e diretórios iniciando com library/xml

  • '**/.svn' – ignora todos diretórios .svn

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

Novo na versão 1.0.

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

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

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

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

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

Novo na versão 1.0.

primary_domain

The name of the default domain. Can also be None to disable a default domain. The default is 'py'. Those objects in other domains (whether the domain name is given explicitly, or selected by a default-domain directive) will have the domain name explicitly prepended when named (e.g., when the default domain is C, Python functions will be named “Python function”, not just “function”).

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.

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

Novo na versão 0.4.

keep_warnings

If true, keep warnings as “system message” paragraphs in the built documents. Regardless of this setting, warnings are always written to the standard error stream when sphinx-build is run.

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

  • download.not_readable

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

  • epub.unknown_project_files

  • epub.duplicated_toc_entry

  • autosectionlabel.*

Pode ser escolhido um dos tipos.

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: Added autosectionlabel.*

Alterado na versão 3.3.0: Added epub.duplicated_toc_entry

needs_sphinx

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

Novo na versão 1.0.

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

needs_extensions

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

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

Novo na versão 1.3.

manpages_url

A URL to cross-reference manpage directives. If this is defined to https://manpages.debian.org/{path}, the :manpage:`man(1)` role will link to <https://manpages.debian.org/man(1)>. The patterns available are:

  • 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

Lista de (type, target) pares (vazios por padrão) que podem ser ignorados quanto à geração de avisos no “modo nitpicky mode”. Toar que type deve incluir o nome do domínio. Exemplo de entradas são: ('py:func', 'int') ou ('envvar', 'LD_LIBRARY_PATH').

Novo na versão 1.1.

nitpick_ignore_regex

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

For example, (r'py:.*', r'foo.*bar\.B.*') will ignore nitpicky warnings for all python entities that start with 'foo' and have 'bar.B' in them, such as ('py:const', 'foo_package.bar.BAZ_VALUE') or ('py:class', 'food.bar.Barman').

Novo na versão 4.1.

numfig

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

Nota

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

Novo na versão 1.3.

numfig_format

A dictionary mapping 'figure', 'table', 'code-block' and 'section' to strings that are used for format of figure numbers. As a special character, %s will be replaced to figure number.

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

Novo na versão 1.3.

numfig_secnum_depth
  • se configurado para 0, figuras, tabelas e bloco de código são continuamente numerados iniciando em 1.

  • se 1 (padrão) números serão x.1, x.2, … com x o número da seção (nível superior de seção); em x. se não houver secão). Isso naturalmente se aplica, somente se numeração foi ativada através da opção :numbered: da diretiva toctree .

  • 2 significa que números serão x.y.1, x.y.2, … se existirem em uma sub-seção (mas aparedcem x.1, x.2, … se existirem sob uma seção e 1, 2, … se não existirem em nenhuma seção nível superior.)

  • etc.

Novo na versão 1.3.

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

smartquotes

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

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

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

smartquotes_action

This string customizes the Smart Quotes transform. See the file smartquotes.py at the Docutils repository for details. The default 'qDe' educates normal quote characters ", ', em- and en-Dashes ---, --, and ellipses ....

Novo na versão 1.6.6.

smartquotes_excludes

Um dict cujo padrão é:

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

Each entry gives a sufficient condition to ignore the smartquotes setting and deactivate the Smart Quotes transform. Accepted keys are as above 'builders' or 'languages'. The values are lists.

Nota

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

Dica

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

make latex O="-D smartquotes_action="

This can follow some make html with no problem, in contrast to the situation from the prior note. It requires Docutils 0.14 or later.

Novo na versão 1.6.6.

user_agent

A User-Agent of Sphinx. It is used for a header on HTTP access (ex. linkcheck, intersphinx and so on). Default is "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 uses requests as a HTTP library internally. Therefore, Sphinx refers a certification file on the directory pointed REQUESTS_CA_BUNDLE environment variable if tls_cacerts not set.

today
today_fmt

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

  • Se configurar today para um valor não vazio, ele será usado.

  • Caso contrário, horário corrente será usado no formato time.strftime() e o formato today_fmt.

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

highlight_language

The default language to highlight source code in. The default is 'default'. It is similar to 'python3'; it is mostly a superset of 'python' but it fallbacks to 'none' without warning if failed. 'python3' and other languages will emit warning if failed.

The value should be a valid Pygments lexer name, see Showing code examples for more details.

Novo na versão 0.5.

Alterado na versão 1.4: The default is now 'default'. If you prefer Python 2 only highlighting, you can set it back to 'python'.

highlight_options

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

Exemplo:

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

A single dictionary of options are also allowed. Then it is recognized as options to the lexer specified by highlight_language:

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

Novo na versão 1.3.

Alterado na versão 3.5: Allow to configure highlight options for multiple languages

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.

add_function_parentheses

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

add_module_names

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

show_authors

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

modindex_common_prefix

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

Novo na versão 0.6.

trim_footnote_reference_space

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

Novo na versão 0.6.

trim_doctest_flags

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

Novo na versão 1.0.

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

strip_signature_backslash

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

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 by figure_language_filename (e.g. the German version of myfigure.png will be myfigure.de.png by default setting) and substitute them for original figures. In the LaTeX builder, a suitable language will be selected as an option for the Babel package. Default is None, which means that no translation will be done.

Novo na versão 0.5.

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

Idiomas atualmente suportados são:

  • ar – Arabic

  • bg – Bulgarian

  • bn – Bengali

  • ca – Catalão

  • cak – Kaqchikel

  • cs – Czech

  • cy – Welsh

  • da – Dinamarquês

  • de – Alemão

  • el – Greek

  • en – Inglês

  • eo – Esperanto

  • es – Espanhol

  • et – Estoniano

  • eu – Basco

  • fa – Iraniano

  • fi – Finlandês

  • fr – Francês

  • he – Hebreu

  • hi – Hindi

  • hi_IN – Hindi (India)

  • hr – Croata

  • hu – Húngaro

  • id – Indonésio

  • it – Italiano

  • ja – Japonês

  • ko – Koreano

  • lt – Lituano

  • lv – Letão

  • mk – Macedônio

  • nb_NO – Norueguês Bokmal

  • ne – Nepalês

  • nl – Holandês

  • pl – Polonês

  • pt – Português

  • pt_BR – Português do Brasil

  • pt_PT – Português Portugal

  • ro – Romeno

  • ru – Russo

  • si – Sinhala

  • sk – Eslovêno

  • sl – Eslovênia

  • sq – Albanian

  • sr – Serbian

  • sr@latin – Serbian (Latin)

  • sr_RS – Serbian (Cyrillic)

  • sv – Sueco

  • ta – Tamil

  • te – Telugu

  • tr – Turco

  • uk_UA – Ucraniano

  • ur – Urdu

  • vi – Vietnamita

  • zh_CN – Chinês Simplificado

  • zh_TW – Chinês Traditional

locale_dirs

Novo na versão 0.5.

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

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

O padrão é ['locales'].

Nota

The -v option for sphinx-build command is useful to check the locale_dirs config works as expected. It emits debug messages if message catalog directory not found.

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

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.

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

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

Alterado na versão 3.3: The string value is now accepted.

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

literal blocks (:: annotation and code-block directive)

Doctest-block

bloco doctest

Raw

conteúdo bruto

imagem

image/figure uri

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

Padrão é [].

Novo na versão 1.3.

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

figure_language_filename

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

  • {root} - O nome do arquivo, incluindo componentes de caminho, porem sem a extensão do arquivo, ex. diretório/arquivo

  • {path} - o caminho do diretório do nome do arquivo, com barra final se não for vazio, ex. diretório/

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

  • {basename} - nome do arquivo sem o caminho do diretório e sem a extensão do arquivo, ex. arquivo

  • {ext} - a extensão do arquivo, ex. .png

  • {language} - idioma da tradução, ex. en

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

Novo na versão 1.4.

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

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

Options for Math

These options influence Math notations.

math_number_all

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

math_eqref_format

A string used for formatting the labels of references to equations. The {number} place-holder stands for the equation number.

Example: 'Eq.{number}' gets rendered as, for example, Eq.10.

math_numfig

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

Novo na versão 1.7.

Opções para saída HTML

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

html_theme

The “theme” that the HTML output should use. See the section about theming. The default is 'alabaster'.

Novo na versão 0.6.

html_theme_options

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

Novo na versão 0.6.

html_theme_path

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

Novo na versão 0.6.

html_style

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

html_title

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

html_short_title

A shorter “title” for the HTML docs. This is used for links in the header and in the HTML Help docs. If not given, it defaults to the value of html_title.

Novo na versão 0.4.

html_baseurl

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

Novo na versão 1.8.

html_codeblock_linenos_style

The style of line numbers for code-blocks.

  • 'table' – display line numbers using <table> tag

  • 'inline' – display line numbers using <span> tag (default)

Novo na versão 3.2.

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

Obsoleto desde a versão 4.0.

html_context

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

Novo na versão 0.5.

If given, this must be the name of an image file (path relative to the configuration directory) that is the logo of the docs, or URL that points an image file for the logo. It is placed at the top of the sidebar; its width should therefore not exceed 200 pixels. Default: 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: Also accepts the URL for the logo file.

html_favicon

If given, this must be the name of an image file (path relative to the configuration directory) that is the favicon of the docs, or URL that points an image file for the favicon. Modern browsers use this as the icon for tabs, windows and bookmarks. It should be a Windows-style icon file (.ico), which is 16x16 or 32x32 pixels large. Default: 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: Also accepts the URL for the favicon.

html_css_files

A list of CSS files. The entry must be a filename string or a tuple containing the filename string and the attributes dictionary. The filename must be relative to the html_static_path, or a full URI with scheme like https://example.org/style.css. The attributes is used for attributes of <link> tag. It defaults to an empty list.

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_files().

Novo na versão 1.8.

Alterado na versão 3.5: Support priority attribute

html_js_files

A list of JavaScript filename. The entry must be a filename string or a tuple containing the filename string and the attributes dictionary. The filename must be relative to the html_static_path, or a full URI with scheme like https://example.org/script.js. The attributes is used for attributes of <script> tag. It defaults to an empty list.

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_files().

Novo na versão 1.8.

Alterado na versão 3.5: Support priority attribute

html_static_path

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

As these files are not meant to be built, they are automatically excluded from source files.

Nota

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

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

Another way to do that, you can also use html_extra_path. It allows to copy dotfiles under the directories.

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

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

Alterado na versão 1.8: The files under html_static_path are excluded from source files.

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.

As these files are not meant to be built, they are automatically excluded from source files.

Novo na versão 1.2.

Alterado na versão 1.4: The dotfiles in the extra directory will be copied to the output directory. And it refers exclude_patterns on copying extra files and directories, and ignores if path matches to patterns.

html_last_updated_fmt

Se não for None, informação ‘Últ. atualização em:’ data e hora é inserida em todo rodapé de página, usando formato da strftime(). Sring vazia é equivalente a '%b %d, %Y' (ou ao equivalente que depende do locale).

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.

Sphinx irá adicionar “permalinks” para cada cabeçalho e descrição de ambiente com sinal de parágrafo que fica visível quando o mouse passa sobre esses links.

Esse valor determina o texto do permalink; normalmente é o caracter "¶". Configurar para None ou string vazia desabilita permalinks.

Novo na versão 0.6: Previamente, isso sempre está ativado.

Alterado na versão 1.1: Pode ser uma string para selecionar texto real do link. Previamente, só booleano era aceito.

Obsoleto desde a versão 3.5: This has been replaced by html_permalinks

If true, Sphinx will add “permalinks” for each heading and description environment. Default: True.

Novo na versão 3.5.

A text for permalinks for each heading and description environment. HTML tags 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.

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

  • Se um valor é uma string simples, ele especifica uma barra lateral configurável a ser adicionada entre as entradas 'sourcelink.html' e 'searchbox.html'. Isso é para compatibilidade com versões Sphinx anteriores a 1.0.

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

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

  • localtoc.html – tabela detalhada de conteúdos do documento atual

  • globaltoc.html – tabela esparça de conteúdo de todo o conjunto documento, modo encolhido

  • relations.html – links que apontam para o anterior e próximo documentos

  • sourcelink.html – link que aponta para o documento atual, se habilitado exibe html_show_sourcelink

  • searchbox.html – caixa “pesquisa rápida”

Exemplo:

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

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

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

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

html_additional_pages

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

Exemplo:

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

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

html_domain_indices

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

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

Novo na versão 1.0.

html_use_index

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

Novo na versão 0.4.

html_split_index

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

Novo na versão 0.4.

html_copy_source

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

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.

Suffix to be appended to source links (see html_show_sourcelink), unless they have this suffix already. Default is '.txt'.

Novo na versão 1.5.

html_use_opensearch

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

html_file_suffix

Esse é o sufixo do nome do arquivo para geração de arquivos html. O padrão é ".html".

Novo na versão 0.4.

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.

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

Novo na versão 1.0.

html_show_sphinx

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

Novo na versão 0.4.

html_output_encoding

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

Novo na versão 1.0.

html_compact_lists

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

Novo na versão 1.0.

html_secnumber_suffix

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

Novo na versão 1.0.

html_search_language

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

Atualmente suporta esses idiomas:

  • da – Dinamarquês

  • nl – Holandês

  • en – Inglês

  • fi – Finlandês

  • fr – Francês

  • de – Alemão

  • hu – Húngaro

  • it – Italiano

  • ja – Japonês

  • no – Norueguês

  • pt – Português

  • ro – Romeno

  • ru – Russo

  • es – Espanhol

  • sv – Sueco

  • tr – Turco

  • zh – Chinês

Acelerando velocidade de montagem

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

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

Alterado na versão 1.3: Adicionado outros idiomas.

html_search_options

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

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

Japonês suporte essas opções:

tipo

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

Pode escolher entre esses módulos:

‘sphinx.search.ja.DefaultSplitter’

Algoritmo TinySegmenter. Esse é o divisor padrão.

‘sphinx.search.ja.MecabSplitter’

MeCab funcionalidade. Usar isso para dividir, ‘mecab’ ou biblioteca link dinâmico (‘libmecab.so’ para linux, ‘libmecab.dll’ para windows) é necessário.

‘sphinx.search.ja.JanomeSplitter’

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

Obsoleto desde a versão 1.6: 'mecab', 'janome' and 'default' is deprecated. To keep compatibility, 'mecab', 'janome' and 'default' are also acceptable.

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

Opções para 'mecab':
dic_enc

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

dict

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

lib

lib option é o nome da biblioteca para encontrar biblioteca MeCab via ctypes se o build do Python não estiver instalado.

Por exemplo:

html_search_options = {
    'type': 'mecab',
    'dic_enc': 'utf-8',
    'dict': '/path/to/mecab.dic',
    'lib': '/path/to/libmecab.so',
}
Opções para 'janome':
user_dic

user_dic option é caminho para arquivo dicionário do Janome.

user_dic_enc

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

Novo na versão 1.1.

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

Chinês suporta essas opções

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

html_search_scorer

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

Novo na versão 1.2.

Se verdadeiro, links para imagens farão referência a imagem original, se não houver opção ‘target’ ou opções relacionadas: ‘scale’, ‘width’, ‘height’. O padrão é True.

Document authors can 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: It is disabled for images having no-scaled-link class

html_math_renderer

The name of math_renderer extension for HTML output. The default is 'mathjax'.

Novo na versão 1.8.

html_experimental_html5_writer

Output is processed with HTML5 writer. Default is False.

Novo na versão 1.6.

Obsoleto desde a versão 2.0.

html4_writer

Output is processed with HTML4 writer. Default is False.

Options for Single HTML output

singlehtml_sidebars

Custom sidebar templates, must be a dictionary that maps document names to template names. And it only allows a key named ‘index’. All other keys are ignored. For more information, refer to html_sidebars. By default, it is same as html_sidebars.

Opções para ajuda saída HTML

htmlhelp_basename

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

htmlhelp_file_suffix

This is the file name suffix for generated HTML help files. The default is ".html".

Novo na versão 2.0.

Suffix for generated links to HTML files. The default is ".html".

Novo na versão 2.0.

Opções para saída Ajuda Apple

Novo na versão 1.3.

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

Nota

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

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

applehelp_bundle_name

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

applehelp_bundle_id

O ID do Conjunto para livro de ajuda itens.

Aviso

Esse valor deve ser configurado para gerar Ajuda Apple.

applehelp_dev_region

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

applehelp_bundle_version

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

applehelp_icon

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

applehelp_kb_product

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

applehelp_kb_url

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

Padrão para None para pesquisa remota.

applehelp_remote_url

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

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

Padrão None para nenhum conteúdo remoto.

applehelp_index_anchors

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

applehelp_min_term_length

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

applehelp_stopwords

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

Idioma

Código

Inglês

en

Alemão

de

Espanhol

es

Francês

fr

Sueco

sv

Húngaro

hu

Italian

it

Padrão para language ou se não configurado vale en.

applehelp_locale

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

Padrão para language ou se não configurado vale en.

applehelp_title

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

applehelp_codesign_identity

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

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

applehelp_codesign_flags

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

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

applehelp_indexer_path

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

applehelp_codesign_path

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

applehelp_disable_external_tools

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

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

O padrão é False.

Opções para saída epub

These options influence the epub output. As this builder derives from the HTML builder, the HTML options also apply where appropriate. The actual values for some of the options is not really important, they just have to be entered into the Dublin Core metadata.

epub_basename

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

epub_theme

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

epub_theme_options

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

Novo na versão 1.2.

epub_title

The title of the document. It defaults to the html_title option but can be set independently for epub creation. It defaults to the project option.

Alterado na versão 2.0: It defaults to the project option.

epub_description

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

Novo na versão 1.4.

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

epub_author

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

epub_contributor

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

Novo na versão 1.4.

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

epub_language

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

epub_publisher

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

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

A unique identifier for the document. This is put in the Dublin Core metadata. You may use a XML’s Name format string. You can’t use hyphen, period, numbers as a first character. The default value is '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

A list of CSS files. The entry must be a filename string or a tuple containing the filename string and the attributes dictionary. For more information, see 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', u'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

This flag determines if sphinx should try to fix image formats that are not supported by some epub readers. At the moment palette images with a small color table are upgraded. You need Pillow, the Python Image Library, installed to use this option. The default value is False because the automatic conversion may lose information.

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.

2

https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode

Opções para saída LaTeX

These options influence LaTeX output.

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 (default if language is 'ja')

'pdflatex'‘s support for Unicode characters is limited.

Nota

2.0 adds to 'pdflatex' support in Latin language document of occasional Cyrillic or Greek letters or words. This is not automatic, see the discussion of the latex_elements 'fontenc' key.

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

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

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

Alterado na versão 2.3: Add uplatex support.

Alterado na versão 4.0: uplatex becomes the default setting of Japanese documents.

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

latex_documents

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

startdocname

String that specifies the document name of the LaTeX file’s master document. All documents referenced by the startdoc document in TOC trees will be included in the LaTeX file. (If you want to use the default root document for your LaTeX build, provide your root_doc here.)

targetname

File name of the LaTeX file in the output directory.

title

LaTeX document title. Can be empty to use the title of the startdoc document. This is inserted as LaTeX markup, so special characters like a backslash or ampersand must be represented by the proper LaTeX commands if they are to be inserted literally.

author

Author for the LaTeX document. The same LaTeX markup caveat as for title applies. Use \\and to separate multiple authors, as in: 'John \\and Sarah' (backslashes must be Python-escaped to reach LaTeX).

theme

LaTeX theme. See latex_theme.

toctree_only

Must be True or False. If true, the startdoc document itself is not included in the output, only the documents referenced by it via TOC trees. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the LaTeX output.

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.

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

This value determines the topmost sectioning unit. It should be chosen from 'part', 'chapter' or 'section'. The default is None; the topmost sectioning unit is switched by documentclass: section is used if documentclass will be howto, otherwise chapter will be used.

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

Novo na versão 1.4.

latex_appendices

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

latex_domain_indices

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

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

Novo na versão 1.0.

latex_show_pagerefs

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

Novo na versão 1.0.

latex_show_urls

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

  • 'no' – não exibir URLs (padrão)

  • 'footnote' – exibir urls nas notas de rodapé.

  • 'inline' – exibir URLs inline em parenteses

Novo na versão 1.0.

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

latex_use_latex_multicolumn

The default is False: it means that Sphinx’s own macros are used for merged cells from grid tables. They allow general contents (literal blocks, lists, blockquotes, …) but may have problems if the tabularcolumns directive was used to inject LaTeX mark-up of the type >{..}, <{..}, @{..} as column specification.

Setting to True means to use LaTeX’s standard \multicolumn; this is incompatible with literal blocks in the horizontally merged cell, and also with multiple paragraphs in such cell if the table is rendered using tabulary.

Novo na versão 1.6.

latex_use_xindy

If True, the PDF build from the LaTeX files created by Sphinx will use xindy (doc) rather than makeindex for preparing the index of general terms (from index usage). This means that words with UTF-8 characters will get ordered correctly for the language.

  • This option is ignored if latex_engine is 'platex' (Japanese documents; mendex replaces makeindex then).

  • The default is True for 'xelatex' or 'lualatex' as makeindex, if any indexed term starts with a non-ascii character, creates .ind files containing invalid bytes for UTF-8 encoding. With 'lualatex' this then breaks the PDF build.

  • The default is False for 'pdflatex' but True is recommended for non-English documents as soon as some indexed terms use non-ascii characters from the language script.

Sphinx adds to xindy base distribution some dedicated support for using 'pdflatex' engine with Cyrillic scripts. And whether with 'pdflatex' or Unicode engines, Cyrillic documents handle correctly the indexing of Latin names, even with diacritics.

Novo na versão 1.8.

latex_elements

Novo na versão 0.5.

Its documentation has moved to 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: In Japanese docs (language is 'ja'), by default 'jreport' is used for 'howto' and 'jsbook' for '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.

Novo na versão 0.6.

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

latex_theme

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

As a built-in LaTeX themes, manual and howto are bundled.

manual

A LaTeX theme for writing a manual. It imports the report document class (Japanese documents use jsbook).

howto

A LaTeX theme for writing an article. It imports the article document class (Japanese documents use jreport rather). latex_appendices is available only for this theme.

It defaults to 'manual'.

Novo na versão 3.0.

latex_theme_options

A dictionary of options that influence the look and feel of the selected theme.

Novo na versão 3.1.

latex_theme_path

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

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

Suffix for section numbers in text output. Default: ". ". Set to " " to suppress the final dot on section numbers.

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 that specifies the document name of the manual page’s master document. All documents referenced by the startdoc document in TOC trees will be included in the manual file. (If you want to use the default root document for your manual pages build, use your root_doc here.)

name

Name of the manual page. This should be a short string without spaces or special characters. It is used to determine the file name as well as the name of the manual page (in the NAME section).

description

Description of the manual page. This is used in the NAME section.

authors

A list of strings with authors, or a single string. Can be an empty string or list if you do not want to automatically generate an AUTHORS section in the manual page.

section

The manual page section. Used for the output file name as well as in the manual page header.

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

If true, make a section directory on build man page. Default is True.

Novo na versão 3.3.

Alterado na versão 4.0: The default is changed to False from True.

Alterado na versão 4.0.2: The default is changed to True from False again.

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 that specifies the document name of the the Texinfo file’s master document. All documents referenced by the startdoc document in TOC trees will be included in the Texinfo file. (If you want to use the default master document for your Texinfo build, provide your root_doc here.)

targetname

File name (no extension) of the Texinfo file in the output directory.

title

Texinfo document title. Can be empty to use the title of the startdoc document. Inserted as Texinfo markup, so special characters like @ and {} will need to be escaped to be inserted literally.

author

Author for the Texinfo document. Inserted as Texinfo markup. Use @* to separate multiple authors, as in: 'John@*Sarah'.

dir_entry

The name that will appear in the top-level DIR menu file.

description

Descriptive text to appear in the top-level DIR menu file.

category

Specifies the section which this entry will appear in the top-level DIR menu file.

toctree_only

Must be True or False. If true, the startdoc document itself is not included in the output, only the documents referenced by it via TOC trees. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the Texinfo output.

Novo na versão 1.1.

texinfo_appendices

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

Novo na versão 1.1.

texinfo_domain_indices

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

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

Novo na versão 1.1.

texinfo_show_urls

Controlear como exibir endereços URL.

  • 'footnote' – Exibir URLs nas notas de rodapé.

  • 'no' – não exibir URLs

  • 'inline' – exibir URLs inline em parenteses

Novo na versão 1.1.

texinfo_no_detailmenu

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

Novo na versão 1.2.

texinfo_elements

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

  • Chaves que podem ser sobrepostas são:

    'paragraphindent'

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

    'exampleindent'

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

    'preamble'

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

    'copying'

    Marcações inseridas com o bloco

  • Chaves que configuram outras opções e podem ser sobrepostas são:

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

Novo na versão 1.1.

Opções para saída QtHelp

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

qthelp_basename

The basename for the qthelp file. It defaults to the project name.

qthelp_namespace

The namespace for the qthelp file. It defaults to 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_request_headers

A dictionary that maps baseurls to HTTP request headers.

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

The value is a dictionary that maps header name to its value.

Exemplo:

linkcheck_request_headers = {
    "https://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

A list of regular expressions that match anchors Sphinx should skip when checking the validity of anchors in links. This allows skipping anchors that a website’s JavaScript adds to control dynamic pages or when triggering an internal REST request. Default is ["^!"].

Nota

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

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

Novo na versão 1.5.

linkcheck_auth

Pass authentication information when doing a linkcheck build.

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

regex_pattern

A regular expression that matches a URI.

auth_info

Authentication information to use for that URI. The value can be anything that is understood by the requests library (see requests Authentication for details).

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

Exemplo:

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

Novo na versão 2.3.

linkcheck_rate_limit_timeout

The linkcheck builder may issue a large number of requests to the same site over a short period of time. This setting controls the builder behavior when servers indicate that requests are rate-limited.

If a server indicates when to retry (using the Retry-After header), linkcheck always follows the server indication.

Otherwise, linkcheck waits for a minute before to retry and keeps doubling the wait time between attempts until it succeeds or exceeds the linkcheck_rate_limit_timeout. By default, the timeout is 5 minutes.

Novo na versão 3.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é

1(1,2)

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.

Options for the C domain

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

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

Novo na versão 3.0.

c_allow_pre_v3

A boolean (default False) controlling whether to parse and try to convert pre-v3 style type directives and type roles.

Novo na versão 3.2.

Obsoleto desde a versão 3.2: Use the directives and roles added in v3.

c_warn_on_allowed_pre_v3

A boolean (default True) controlling whether to warn when a pre-v3 style type directive/role is parsed and converted.

Novo na versão 3.2.

Obsoleto desde a versão 3.2: Use the directives and roles added in v3.

Opções para domínio C++

cpp_index_common_prefix

A list of prefixes that will be ignored when sorting C++ objects in the global index. For example ['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

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

Novo na versão 1.5.

Options for the Python domain

python_use_unqualified_type_names

If true, suppress the module name of the python reference if it can be resolved. The default is False.

Novo na versão 4.0.

Nota

This configuration is still in experimental

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 execfile()d 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 = u'test'
copyright = u'2016, test'
author = u'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 = u'test'
# The full version, including alpha/beta/rc tags.
release = u'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 = u'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', u'test Documentation',
     u'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', u'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', u'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

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