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
.