26.2. "pydoc" --- Gerador de documentação e sistema de ajuda online
*******************************************************************

**Código Fonte:** Lib/pydoc.py

======================================================================

O módulo "pydoc" gera automaticamente a documentação dos módulos
Python. A documentação pode ser apresentada como páginas de texto no
console, servida em um navegador web ou salva em arquivos HTML.

Para módulos, classes, funções e métodos, a documentação exibida é
derivada da docstring (ou seja, o atributo "__doc__") do objeto, e
recursivamente de seus membros documentáveis. Se não houver docstring,
"pydoc" tenta obter uma descrição do bloco de linhas de comentário
logo acima da definição da classe, função ou método no arquivo fonte,
ou no topo do módulo (consulte "inspect.getcomments()").

A função embutida "help()" invoca o sistema de ajuda online no
interpretador interativo, que usa "pydoc" para gerar sua documentação
como texto no console. A mesma documentação de texto também pode ser
vista de fora do interpretador Python executando **pydoc** como um
script no prompt de comando do sistema operacional. Por exemplo,
executar

   pydoc sys

em um prompt de console exibirá a documentação do módulo "sys", em um
estilo semelhante às páginas de manual mostradas pelo comando Unix
**man**. O argumento para **pydoc** pode ser o nome de uma função,
módulo ou pacote, ou uma referência pontilhada a uma classe, método ou
função dentro de um módulo ou módulo em um pacote. Se o argumento para
**pydoc** parecer um caminho (ou seja, ele contém o separador de
caminho para o seu sistema operacional, como uma barra no Unix) e se
refere a um arquivo fonte Python existente, então a documentação é
produzida para esse arquivo.

Nota:

  Para encontrar objetos e sua documentação, "pydoc" importa os
  módulos a serem documentados. Portanto, qualquer código no nível do
  módulo será executado nessa ocasião. Use uma proteção "if __name__
  == '__main__':" para executar código apenas quando um arquivo é
  chamado como um script e não apenas importado.

Ao imprimir a saída para o console, **pydoc** tenta paginar a saída
para facilitar a leitura. Se a variável de ambiente "PAGER" estiver
definida, **pydoc** usará seu valor como um programa de paginação.

Especificar um sinalizador "-w" antes do argumento fará com que a
documentação HTML seja escrita em um arquivo no diretório atual, ao
invés de exibir texto no console.

Especificar um sinalizador "-k" antes do argumento irá pesquisar as
linhas de sinopse de todos os módulos disponíveis para a palavra
reservada fornecida como o argumento, novamente de uma maneira
semelhante ao comando Unix **man**. A linha de sinopse de um módulo é
a primeira linha de sua string de documentação.

Você também pode usar **pydoc** para iniciar um servidor HTTP na
máquina local que servirá a documentação para os navegadores web
visitantes. **pydoc -p 1234** irá iniciar um servidor HTTP na porta
1234, permitindo que você navegue pela documentação em
"http://localhost:1234/" em seu navegador preferido. Especificar "0"
como o número da porta irá selecionar uma porta não utilizada
arbitrária.

**pydoc -b** irá iniciar o servidor e, adicionalmente, abrir um
navegador da web para uma página de índice do módulo. Cada página
exibida tem uma barra de navegação na parte superior onde você pode
escolher *Get* para obter ajuda em um item individual, *Search* para
pesquisar todos os módulos com uma palavra reservada em sua linha de
sinopse e ir para as páginas de índice do módulo em *Module index*,
tópicos em *Topics* e palavras reservadas em *Keywords*.

Quando **pydoc** gera documentação, ele usa o ambiente atual e o
caminho para localizar os módulos. Assim, invocar **pydoc spam**
documenta precisamente a versão do módulo que você obteria se
iniciasse o interpretador Python e digitasse "import spam".

Os documentos do módulo para os módulos principais são assumidos para
residir em "https://docs.python.org/X.Y/library/" onde "X" e "Y" são
os números de versão principal e secundária do interpretador Python.
Isso pode ser substituído definindo a variável de ambiente
"PYTHONDOCS" para uma URL diferente ou para um diretório local
contendo as páginas do Manual de Referência da Biblioteca.

Alterado na versão 3.2: Adicionada a opção "-b".

Alterado na versão 3.3: A opção de linha de comando "-g" foi removida.

Alterado na versão 3.4: "pydoc" agora usa "inspect.signature()" em vez
de "inspect.getfullargspec()" para extrair informações de assinatura
de chamáveis.
