pydoc — Gerador de documentação e sistema de ajuda online

Código-fonte: Lib/pydoc.py

The pydoc module automatically generates documentation from Python modules. The documentation can be presented as pages of text on the console, served to a web browser, or saved to HTML files.

For modules, classes, functions and methods, the displayed documentation is derived from the docstring (i.e. the __doc__ attribute) of the object, and recursively of its documentable members. If there is no docstring, pydoc tries to obtain a description from the block of comment lines just above the definition of the class, function or method in the source file, or at the top of the module (see inspect.getcomments()).

The built-in function help() invokes the online help system in the interactive interpreter, which uses pydoc to generate its documentation as text on the console. The same text documentation can also be viewed from outside the Python interpreter by running pydoc as a script at the operating system’s command prompt. For example, running

python -m 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

In order to find objects and their documentation, pydoc imports the module(s) to be documented. Therefore, any code on module level will be executed on that occasion. Use an if __name__ == '__main__': guard to only execute code when a file is invoked as a script and not just imported.

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. python -m 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.

python -m pydoc -n <hostname> irá iniciar o servidor ouvindo no nome de host fornecido. Por padrão, o nome de host é “localhost”, mas se você deseja que o servidor seja acessado por outras máquinas, você pode alterar o nome de host ao qual o servidor responde. Durante o desenvolvimento, isso é especialmente útil se você deseja executar o pydoc de dentro de um contêiner.

python -m 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.

Module docs for core modules are assumed to reside in https://docs.python.org/X.Y/library/ where X and Y are the major and minor version numbers of the Python interpreter. This can be overridden by setting the PYTHONDOCS environment variable to a different URL or to a local directory containing the Library Reference Manual pages.

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 now uses inspect.signature() rather than inspect.getfullargspec() to extract signature information from callables.

Alterado na versão 3.7: Adicionada a opção -n.