Documentation

    A 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 file.

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

    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 (see). 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 is far and away the most popular Python documentationtool. Use it. It converts 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:. 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

    reStructuredText

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

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

    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:

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

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

    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:

    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:

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

    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

    You might see these in the wild. Use Sphinx.

    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 builds Unix manuals. It converts human readable textfiles to rofffor terminal display, and also to HTML for the web.
    Epydoc
    Epydoc is discontinued. Use instead.
    MkDocs
    MkDocs is a fast and simple static site generator that’s geared towardsbuilding project documentation with Markdown.