Glossário

construtor

Um classe (herdada de Builder) que recebe documentos analisados e executa certas ações neles. Normalmente, construtores traduzem os documentos para um formato de saída, mas também é possível usar construtores que, por exemplo, verificam links quebrados na documentação ou constroem informações de cobertura.

Veja Construtores para uma visão geral dos construtores embutidos do Sphinx.

diretório de configuração

O diretório contendo o conf.py. Por padrão, esse é o mesmo nomeado no diretório fonte, mas pode ser modificado usando a opção da linha de comando -c.

diretiva

Um elemento de marcação reStructuredText que permite marcar um bloco de conteúdo com significado especial. Diretivas são fornecidas não só pelo docutils, mas por extensões configuráveis do Sphinx podem adicionar suas próprias funcionalidades. A diretiva básica tem a sintaxe como essa:

.. directive-name:: argument ...
   :option: value

   Content of the directive.

Consulte Diretivas para mais informações.

nome do documento

Arquivos fonte reStructuredText podem possuir diferentes extensões (alguns usam .txt, outros .rst – a extensão pode ser configurada com source_suffix) e diferentes S.O. usam separador de diretório distinto. Sphinx abstrai esses separadores: nomes dos documentos são sempre relativos ao diretório fonte, a extensão é subtraída e os separadores de caminho são convertidos em barras. Todos valores, parâmetros e referências a “documentos” devem ser tais nomes dos documentos.

Exemplos para nomes dos documentos são index, library/zipfile ou reference/datamodel/types. Note que não há barra no início nem no final.

domínio

Um domínio é uma coleção de marcações (reStructuredText diretiva e papel) para descrever e vincular o objeto ao qual pertencem conjuntamente, por exemplo, elementos de uma linguagem de programação. Nomes e papéis de diretivas em um domínio têm nomes como domínio:nome como, por exemplo, py:function.

Ter domínios significa que não há problemas de nomenclatura quando um conjunto de documentação deseja fazer referência a Classes C++ e Python. Isso também significa que as extensões que suportam a documentação de novos idiomas são muito mais fáceis de serem escritas.

Para mais informações, consulte Domínios.

ambiente

A estrutura onde a informação sobre todos os documentos será salva e usada para referência cruzada. O ambiente é obtido após o estágio de passagem, por isso sucessivas execuções são necessárias somente para ler e passar documentos modificados.

extensão

Um papel personalizado, uma diretiva personalizada ou outro aspecto do Sphinx que permite aos usuários modificar qualquer aspecto do processo de construção dentro do Sphinx.

Para mais informações, consulte Extensões.

documento mestre
documento raiz

O documento que contém a diretiva raiz toctree .

objeto

O bloco básico de construção de documentação Sphinx. Toda “diretiva de objeto” (p. ex., py:function ou object) cria esse tipo de bloco e muitos objetos podem fazer essa referência cruzada.

RemoveInSphinxXXXWarning

A funcionalidade para a qual é exibido o aviso de versão Sphinx-XXX. Normalmente tem como causa extensões Sphinx que são descontinuadas para uso. Veja também Avisos de Obsoleto.

papel

Um elemento de marcação reStructuredText que permite marcar um pedaço de texto. Como diretivas, os papéis são extensíveis. A sintaxe básica é assim: :rolename:`content`. Veja Marcação Inline para detalhes.

diretório fonte

O diretório que, incluindo seus subdiretórios, contém todos os arquivos fontes de um projeto Sphinx.

reStructuredText

Uma sintaxe de marcação de texto plano e sistema de análise de marcação de texto simples e fácil de ler, que você vê, é o que você obtém.