Readability is a primary focus for Python developers, in both project and code documentation. Following some simple best practices can save both you and others a lot of time.
A README file at the root directory should give general information to both users and maintainers of a project. It should be raw text or written in some very easy to read markup, such as reStructuredText or Markdown. It should contain a few lines explaining the purpose of the project or library (without assuming the user knows anything about the project), the url of the main source for the software, and some basic credit information. This file is the main entry point for readers of the code.
An INSTALL file is less necessary with Python. The installation instructions are often reduced to one command, such as pip install module or python setup.py install and added to the README file.
A LICENSE file should always be present and specify the license under which the software is made available to the public.
A TODO file or a TODO section in README should list the planned development for the code.
A CHANGELOG file or section in README should compile a short overview of the changes in the code base for the latest versions.
Depending on the project, your documentation might include some or all of the following components:
Sphinx is far and away the most popular Python documentation tool. Use it. It converts reStructuredText markup language into a range of output formats including HTML, LaTeX (for printable PDF 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 to your source repository so that rebuilding your documentation will happen automatically.
Comments clarify the code and they are added with purpose of making the code 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): """Returns the square root of self times self.""" ...
In general, follow the comment section of PEP 8 (the “Python Style Guide”).
Some tools use docstrings to embed more-than-documentation behavior, such as unit test logic. Those can be nice, but you won’t ever go wrong with vanilla “here’s what this does.”
These aren’t interchangeable. For a function or class, the leading comment block is a programmer’s note. The docstring describes the operation 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.""" ...
Further reading on docstrings: PEP 257
You might see these in the wild. Use Sphinx.