Document

In order for your software package to be useful, documentation is required that describes how your software can be installed, operated, used and improved:

• Those who want to use your package need information,

  • what problems your software solves and what the main features and limitations of the software are (README)

  • how the software can be used as an example

  • what changes have come in more recent software versions (CHANGELOG)

• Those who want to run the software need an installation guide for your software and the required dependencies.

• Those who want to improve the software need information about

  • how to help improve the product with bug fixes (CONTRIBUTING)

  • how to communicate with others (CODE_OF_CONDUCT)

All together need information on how the product is licensed (LICENSE file or LICENSES folder) and how to get help if needed.

See also

• Eric Holscher: Why You Shouldn’t Use “Markdown” for Documentation

• Tom Johnson: 10 reasons for moving away from DITA

• Tom Johnson: Jekyll versus DITA

• Google developer documentation style guide

• Google Technical Writing Courses for Engineers

Badges

Some of this information and more can be accessed as badges. They are helpful in getting a quick overview of a product. For the cookiecutter-namespace-template these are, for example:

You can also create your own badges, for example:

See also

• shields.io

Sphinx

For extensive documentation you can, for example, use Sphinx, a documentation tool that converts reStructuredText into HTML or PDF, EPub and man pages. The Python Basics are also created with Sphinx. To get a first impression of Sphinx, you can have a look at the source code of this page by following the link Sources.

Originally, Sphinx was developed for the documentation of Python and is now used in almost all Python projects, including NumPy and SciPy, Matplotlib, Pandas and SQLAlchemy.

The Sphinx autodoc feature, which can be used to create documentation from Python Docstrings, may also be conducive to the spread of Sphinx among Python developers. Overall, Sphinx allows developers to create complete documentation in place. Often the documentation is also stored in the same Git repository, so that the creation of the latest software documentation remains easy.

Sphinx is also used in projects outside the Python community, e.g. for the documentation of the Linux kernel: Kernel documentation update.

Read the Docs was developed to forther simplify documentation. Read the Docs makes it easy to create and publish documentation after each commit.

For project documentation, visualising Git feature branches and tags with git-big-picture can be helpful.

Note

If the content of long_description in setup() is written in reStructured Text, it is displayed as well-formatted HTML on ther Python Package Index (PyPI).

Other documentation tools

Pycco

is a Python port of Docco.