如何在Python中記錄模塊？

Question

就是這樣。如果你想記錄一個函數或一個類，你可以在該定義之後加一個字符串。例如：

def foo(): 
    """This function does nothing.""" 
    pass 

但是模塊呢？我如何記錄file.py的功能？

Answer 1

對於軟件包，您可以在__init__.py中記錄它。 對於模塊，您可以簡單地在模塊文件中添加文檔字符串。

的所有信息是在這裏：http://www.python.org/dev/peps/pep-0257/

Answer 2

很簡單，您只需在模塊的頂部添加文檔字符串即可。

Answer 3

你這樣做完全一樣的方式。將一個字符串作爲模塊中的第一條語句。

Answer 4

將您的文檔字符串添加爲first statement in the module。

因爲我喜歡看一個例子：

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

import foo 

# ... 

Answer 5

這裏是模塊如何被記錄的Example Google Style Python Docstrings。基本上有一個關於模塊的信息，如何執行它以及關於模塊級別變量和ToDo項目列表的信息。

"""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 
... 
...