Glossário

construtor

Classe (herdada de Builder) que controla ou executa certas ações nesses quais documentos. Normalmente, construtores traduzem documentos para um formato de saída, mas também é possível usar construtores que, por exemplo, verificam links inconsistentes na documentação ou constróem informações de cobertura.

Veja Builders para uma visão geral dos construtores integrados do Sphinx.

diretório de configuração

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

diretiva

Um elemento marcado de 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 ter suas próprias funcionalidades. A diretiva básica tem a sintaxe como essa:

.. directivename:: argument ...
   :option: value

   Content of the directive.

Consulte Diretivas para mais informações.

nome do documento

Arquivos fontes reST 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 document names os quais são sempre relativos ao source directory, a extensão é subtraída e os separadores são convertidos para barras. Todos valores, parâmetros e referências a “documents” devem ser nomes de documentos.

Exemplos para nomes de documento são index`, library/zipfile, ou reference/datamodel/types. Note que não há barra inicial nem final.

domínio

Um domínio é uma coleção de marcações (reStructuredText directivee role) para descrever e ligar o objectao qual pertencem conjuntamente, ex: elementos de uma linguagem de programação. Nomes de diretiva e regra em um nome de domínio parecem com domain:name ex: 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 personalizado role, directive ou outro aspecto do Sphinx que permite aos usuários modificar qualquer aspecto do processo de criação no Sphinx.

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

documento principal

O documento que contém a diretiva raiz toctree .

documento raiz

Mesmo que documento mestre.

objeto

O bloco básico de construção de documentação Sphinx. Toda “diretiva de objeto” (ex: 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 Sphinx-XXX versão. Normalmente tem como causa extensões que são tornadas obsoletas para uso. Ver 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 no qual, incluindo seus subdiretórios, contem 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.