Como faço para documentar um módulo em Python?

votos
44

É isso aí. Se você deseja documentar uma função ou uma classe, você colocar uma corda logo após a definição. Por exemplo:

def foo():
    This function does nothing.
    pass

Mas o que dizer de um módulo? Como posso documentar o que um file.py faz?

Publicado 04/09/2008 em 17:06
fonte usuário
Em outras línguas...                            


5 respostas

votos
38

Para os pacotes, você pode documentá-lo em __init__.py. Para os módulos, você pode adicionar uma docstring simplesmente no arquivo módulo.

Toda a informação está aqui: http://www.python.org/dev/peps/pep-0257/

Respondeu 04/09/2008 em 17:12
fonte usuário

votos
30

Adicionar uma docstring como a primeira declaração no módulo .

Desde que eu gosto de ver um exemplo:

"""
Your module's verbose yet thorough docstring.
"""

import foo

# ...
Respondeu 04/05/2014 em 00:29
fonte usuário

votos
6

Você fazê-lo da mesma maneira. Colocar uma corda em como a primeira instrução no módulo.

Respondeu 04/09/2008 em 17:12
fonte usuário

votos
5

Aqui está um exemplo Google Estilo Python docstrings sobre como módulo pode ser documentado. Basicamente, há uma informação sobre um módulo, como executá-lo e informações sobre as variáveis nível de módulo e lista de itens para fazer.

"""Example Google style docstrings.

This module demonstrates documentation as specified by the `Google
Python Style Guide`_. Docstrings may extend over multiple lines.
Sections are created with a section header and a colon followed by a
block of indented text.

Example:
    Examples can be given using either the ``Example`` or ``Examples``
    sections. Sections support any reStructuredText formatting, including
    literal blocks::

        $ python example_google.py

Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.

Attributes:
    module_level_variable1 (int): Module level variables may be documented in
        either the ``Attributes`` section of the module docstring, or in an
        inline docstring immediately following the variable.

        Either form is acceptable, but the two should not be mixed. Choose
        one convention to document module level variables and be consistent
        with it.

Todo:
    * For module TODOs
    * You have to also use ``sphinx.ext.todo`` extension

.. _Google Python Style Guide:   
http://google.github.io/styleguide/pyguide.html

"""

module_level_variable1 = 12345

def my_function():   
    pass 
... 
...
Respondeu 28/01/2017 em 19:34
fonte usuário

votos
4

É fácil, basta adicionar uma docstring no topo do módulo.

Respondeu 04/09/2008 em 17:12
fonte usuário

Cookies help us deliver our services. By using our services, you agree to our use of cookies. Learn more