Documentation

Readability is a primary focus for Python developers, in both projectand code documentation. Following some simple best practices can saveboth you and others a lot of time.

Project Documentation

A README file at the root directory should give general informationto both users and maintainers of a project. It should be raw text orwritten in some very easy to read markup, such as reStructuredTextor Markdown. It should contain a few lines explaining the purpose of theproject or library (without assuming the user knows anything about theproject), the URL of the main source for the software, and some basic creditinformation. This file is the main entry point for readers of the code.

An INSTALL file is less necessary with Python. The installationinstructions are often reduced to one command, such as pip install
module or python setup.py install, and added to the READMEfile.

A LICENSE file should always be present and specify the licenseunder which the software is made available to the public.

A TODO file or a TODO section in README should list theplanned development for the code.

A CHANGELOG file or section in README should compile a shortoverview of the changes in the code base for the latest versions.

Project Publication

Depending on the project, your documentation might include some or allof the following components:

• An introduction should show a very short overview of what can bedone with the product, using one or two extremely simplified usecases. This is the thirty-second pitch for your project.
• A tutorial should show some primary use cases in more detail. The readerwill follow a step-by-step procedure to set-up a working prototype.
• An API reference is typically generated from the code (seedocstrings). It will list all publicly availableinterfaces, parameters, and return values.
• Developer documentation is intended for potential contributors. This caninclude code convention and general design strategy of the project.

Sphinx

Sphinx is far and away the most popular Python documentationtool. Use it. It converts reStructuredText markup languageinto a range of output formats including HTML, LaTeX (for printablePDF versions), manual pages, and plain text.

There is also great, free hosting for your Sphinx docs:Read The Docs. Use it. You can configure it with commit hooks toyour source repository so that rebuilding your documentation willhappen automatically.

When run, Sphinx will import your code and using Python’s introspectionfeatures it will extract all function, method, and class signatures. It willalso extract the accompanying docstrings, and compile it all into wellstructured and easily readable documentation for your project.

Note

Sphinx is famous for its API generation, but it also works wellfor general project documentation. This Guide is built withSphinx and is hosted on Read The Docs

reStructuredText

Most Python documentation is written with reStructuredText. It’s likeMarkdown with all the optional extensions built in.

The reStructuredText Primer and the reStructuredText QuickReference should help you familiarize yourself with its syntax.

Code Documentation Advice

Comments clarify the code and they are added with purpose of making thecode easier to understand. In Python, comments begin with a hash(number sign) (#).

In Python, docstrings describe modules, classes, and functions:

def square_and_rooter(x):
    """Return the square root of self times self."""
    ...

In general, follow the comment section of PEP 8#comments (the “Python StyleGuide”). More information about docstrings can be found at PEP 0257#specification (The Docstring Conventions Guide).

Commenting Sections of Code

Do not use triple-quote strings to comment code. This is not a goodpractice, because line-oriented command-line tools such as grep willnot be aware that the commented code is inactive. It is better to addhashes at the proper indentation level for every commented line. Youreditor probably has the ability to do this easily, and it is worthlearning the comment/uncomment toggle.

Docstrings and Magic

Some tools use docstrings to embed more-than-documentation behavior,such as unit test logic. Those can be nice, but you won’t ever gowrong with vanilla “here’s what this does.”

Tools like Sphinx will parse your docstrings as reStructuredText and render itcorrectly as HTML. This makes it very easy to embed snippets of example code ina project’s documentation.

Additionally, Doctest will read all embedded docstrings that look like inputfrom the Python commandline (prefixed with “>>>”) and run them, checking to seeif the output of the command matches the text on the following line. Thisallows developers to embed real examples and usage of functions alongsidetheir source code, and as a side effect, it also ensures that their code istested and works.

def my_function(a, b):
    """
    >>> my_function(2, 3)
    6
    >>> my_function('a', 3)
    'aaa'
    """
    return a * b

Docstrings versus Block comments

These aren’t interchangeable. For a function or class, the leadingcomment block is a programmer’s note. The docstring describes theoperation of the function or class:

# This function slows down program execution for some reason.
def square_and_rooter(x):
    """Returns the square root of self times self."""
    ...

Unlike block comments, docstrings are built into the Python language itself.This means you can use all of Python’s powerful introspection capabilities toaccess docstrings at runtime, compared with comments which are optimized out.Docstrings are accessible from both the doc dunder attribute for almostevery Python object, as well as with the built in help() function.

While block comments are usually used to explain what a section of code isdoing, or the specifics of an algorithm, docstrings are more intended forexplaining to other users of your code (or you in 6 months time) how aparticular function can be used and the general purpose of a function, class,or module.

Writing Docstrings

Depending on the complexity of the function, method, or class being written, aone-line docstring may be perfectly appropriate. These are generally used forreally obvious cases, such as:

def add(a, b):
    """Add two numbers and return the result."""
    return a + b

The docstring should describe the function in a way that is easy to understand.For simple cases like trivial functions and classes, simply embedding thefunction’s signature (i.e. add(a, b) -> result) in the docstring isunnecessary. This is because with Python’s inspect module, it is alreadyquite easy to find this information if needed, and it is also readily availableby reading the source code.

In larger or more complex projects however, it is often a good idea to givemore information about a function, what it does, any exceptions it may raise,what it returns, or relevant details about the parameters.

For more detailed documentation of code a popular style is the one used for theNumPy project, often called NumPy style docstrings. While it can take up morelines than the previous example, it allows the developer to include a lotmore information about a method, function, or class.

def random_number_generator(arg1, arg2):
    """
    Summary line.
 
    Extended description of function.
 
    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2
 
    Returns
    -------
    int
        Description of return value
 
    """
    return 42

The sphinx.ext.napoleon plugin allows Sphinx to parse this style ofdocstrings, making it easy to incorporate NumPy style docstrings into yourproject.

At the end of the day, it doesn’t really matter what style is used for writingdocstrings; their purpose is to serve as documentation for anyone who may needto read or make changes to your code. As long as it is correct, understandable,and gets the relevant points across then it has done the job it was designed todo.

For further reading on docstrings, feel free to consult PEP 257

Other Tools

You might see these in the wild. Use Sphinx.

Pycco

Pycco is a “literate-programming-style documentation generator”and is a port of the node.js Docco. It makes code into aside-by-side HTML code and documentation.

Ronn

Ronn builds Unix manuals. It converts human readable textfiles to rofffor terminal display, and also to HTML for the web.

Epydoc

Epydoc is discontinued. Use Sphinx instead.

MkDocs

MkDocs is a fast and simple static site generator that’s geared towardsbuilding project documentation with Markdown.

原文: https://docs.python-guide.org/writing/documentation/