O domínio padrão

Adicionado na versão 1.0.

O chamado domínio “padrão” coleta todas as marcações que não garantem um domínio próprio. Suas diretivas e papéis não são prefixados com um nome de domínio.

O domínio padrão também é onde as descrições de objetos personalizados, adicionadas usando a API add_object_type(), são colocadas.

Existe um conjunto de diretivas que permitem documentar programas de linha de comando:

.. option:: name args, name args, ...

Descreve um argumento ou opção de linha de comando. Os nomes dos argumentos das opções devem ser colocados entre colchetes angulares. Exemplos:

.. option:: dest_dir

   Destination directory.

.. option:: -m <module>, --module <module>

   Run a module as a script.

A diretiva criará alvos de referência cruzada para as opções fornecidas, referenciáveis ​​por option (no caso de exemplo, você usaria algo como :option:`dest_dir`, :option :`-m`, ou :option:`--module`).

Alterado na versão 5.3: Pode-se fazer referência cruzada incluindo um valor de opção: :option:`--module=foobar`, :option:`--module[=foobar]` ou :option:`--module foobar`.

Use option_emphasise_placeholders para analisar a “parte variável” de um texto literal (similarmente ao papel samp).

A diretiva cmdoption é um alias descontinuado para a diretiva option.

.. confval:: name

Adicionado na versão 7.4.

Descreve um valor de configuração ou uma definição que o código ou programa documentado usa ou define. Referenciável por confval.

:type: (text)

Descreve o tipo do valor de configuração. Isso é opcional e, se especificado, será interpretado como reStructuredText.

:default: (text)

Descreve o valor padrão do valor de configuração. Isso é opcional e, se especificado, será interpretado como reStructuredText.

Exemplo:

.. confval:: the_answer
   :type: ``int`` (a *number*)
   :default: **42**

   This is a setting that controls the value of the answer.

será renderizado da seguinte maneira:

the_answer
Type:
int (a number)
Default:
42

This is a setting that controls the value of the answer.

.. envvar:: name

Descreve uma variável de ambiente que o código ou programa documentado usa ou define. Referenciável por envvar.

.. program:: name

Assim como py:currentmodule, esta diretiva não produz saída. Em vez disso, serve para notificar o Sphinx que todas as diretivas option documentam opções para o programa chamado name.

Se você usar program, você tem que qualificar as referências em seus papéis option pelo nome do programa, então se você tiver a seguinte situação

.. program:: rm

.. option:: -r

   Work recursively.

.. program:: svn

.. option:: -r <revision>

   Specify the revision to work upon.

então :option:`rm -r` se referiria à primeira opção, enquanto :option:`svn -r` se referiria à segunda.

Se None for passado para o argumento, a diretiva irá redefinir o nome do programa atual.

O nome do programa pode conter espaços (caso você queira documentar subcomandos como svn add e svn commit separadamente).

Adicionado na versão 0.5.

Há também uma diretiva de descrição de objeto muito genérica, que não está vinculada a nenhum domínio:

.. describe:: text
.. object:: text

Esta diretiva produz a mesma formatação específica fornecida pelos domínios, mas não cria entradas de índice ou alvos de referência cruzada. Exemplo:

.. describe:: PAPER

   You can set this variable to select a paper size.