pydoc – Documentação de módulos Python

Em mais um post sobre documentação, vamos conhecer hoje o pydoc [1]. O pydoc é um módulo que gera documentação (em formato amigável) sobre módulos Python, a partir dos docstrings que estão presentes nestes. A documentação pode ser apresentada em mais de uma forma. Uma delas, é o formato manpage [2]. Para ver a documentação de um módulo em formato manpage, podemos invocar o pydoc através de um shell do sistema operacional:

$ pydoc timeit

A documentação pode ser vista na tela abaixo:

Uma vantagem óbvia disso é não precisar abrir um shell python para apenas tirar uma dúvida sobre algum método. Além da visualização manpage-style, o pydoc também gera documentação em formato HTML.

$ pydoc -w timeit
wrote timeit.html

O comando acima gera um arquivo com a extensão html com o nome do módulo em questão, para ser visualizado em um browser.

Além de mostrar a documentação em formato manpage e de gerar arquivos html com a documentação, também é possível “levantar” um servidor web que irá servir as páginas html com a documentação dos módulos disponíveis no sistema. Para isso, basta chamar o pydoc com a opção -p, passando o número da porta onde o servidor irá escutar como argumento.

$ pydoc -p 8080
pydoc server ready at http://localhost:8080/

Acessando no browser o endereço localhost:8080, é possível navegar nas páginas de documentação dos módulos.

Por fim, existe outra opção que abre uma interface gráfica onde o usuário poderá procurar pelo módulo sobre o qual deseja ver a documentação e abrir o html correspondente no browser.

Na figura acima, ao dar duplo-clique sobre um dos itens retornados pela busca, é aberto no browser o documento html correspondente ao módulo escolhido.

É claro que, além dessas formas de visualizar a documentação dos módulos, também podemos usar o tradicional builtin help() para ver a documentação dentro do shell Python.

[1] http://docs.python.org/library/pydoc.html

[2] https://en.wikipedia.org/wiki/Man_page

Publicado por

Valdir Stumm Jr

Postado no

14 de junho de 2012

Publicado em

dicas rápidas, documentação, shell

comentários

3 Comentários

Acesso fácil à documentação com ipython

Para quem não sabe, quando desejamos informações de ajuda sobre algum módulo/método/builtin, podemos invocar o builtin help(). Por exemplo, quero saber detalhes sobre a função len():

>>> help(len)
Help on built-in function len in module __builtin__:
len(...)
 len(object) -> integer
 Return the number of items of a sequence or mapping.
(END)

Isso irá ler o atributo __doc__ do objeto em questão. Mas, em minha opinião de preguiçoso, é um pouco chato sempre chamar a função help(), passando como argumento o objeto do qual desejamos mais informações. Se você concorda comigo, saiba que o ipython [1] fornece um “atalho” bem simples para acessarmos a documentação de determinado objeto. Basta adicionar um ponto de interrogração ao final do nome do objeto, que o ipython mostra o texto de ajuda. Veja a figura abaixo:

iPython mostrando informações sobre método.

Além da interrogação simples (?), podemos utilizar também a interrogação dupla (??) para obter informações adicionais sobre o método/módulo, incluindo o seu código-fonte, quando disponível. Veja abaixo: