How to document a module in Python?

Question

What is it. If you want to document a function or class, you put the line immediately after the definition. For example:

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

But what about the module? How can I document what a .py file does?

Answer 1

For packages, you can document it in __init__.py . For modules, you can add docstring just to the module file.

All information here: http://www.python.org/dev/peps/pep-0257/

Answer 2

Add the documentation line as the first statement in the module .

 """ Your module verbose yet thorough docstring. """ import foo # ... 

For packages, you can add your documentation line to __init__.py .

Answer 3

Here is an example of a Python Google Style style string about how a module can be documented. Basically, there is information about the module, how to execute it, as well as information about the module level variables and a list of ToDo elements.

 """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.imtqy.com/styleguide/pyguide.html """ module_level_variable1 = 12345 def my_function(): pass ... ... 

Answer 4

You do it the exact same way. Put the line as the first statement in the module.

Answer 5

Easy, you just add a document line at the top of the module.

Answer 6

For PyPI packages:

If you add similar lines to the __init__.py file as shown below

 """ Please refer to the documentation provided in the README.md, which can be found at gorpyter PyPI URL: https://pypi.org/project/gorpyter/ """ # <IMPORT_DEPENDENCIES> def setup(): """Verify your Python and R dependencies.""" 

Then you will get this with the daily help function.

help(<YOUR_PACKAGE>)

 DESCRIPTION Please refer to the documentation provided in the README.md, which can be found at gorpyter PyPI URL: https://pypi.org/project/gorpyter/ FUNCTIONS setup() Verify your Python and R dependencies. 

Please note that my DESCRIPTION help is caused by the presence of this first line of documentation at the very top of the file.