Documentation

We write a lot of documentation. Since we believe, that documentation is a crucial factor which defines project success or failure.

Here’s how we write docs for django projects.

Dependencies

We are using sphinx as a documentation builder. We use sphinx.ext.napoleon to write pretty docstrings inside the source code. We also use sphinx_autodoc_typehints to inject type annotations into docs.

We use pyproject.toml as the source of truth for our deps. All docs-related packages are stored under docs extra.

To install them use:

poetry install --with=docs

Structure

We use a clear structure for this documentation.

  • pages/template contains docs from wemake-django-template. These files should not be modified locally. If you have any kind of question or problems, just open an issue on github

  • pages/project contains everything related to the project itself. Usage examples, an auto-generated documentation from your source code, configuration, business, and project goals

  • documents contains different non-sphinx documents like doc files, spreadsheets, and mockups

Please, do not mix it up.

How to structure project docs

It is a good practice to write a single rst document for every single py file. Obviously, rst structure fully copies the structure of your source code. This way it is very easy to navigate through the docs, since you already know the structure.

For each django application we tend to create a file called index.rst which is considered the main file for the application.

And pages/project/index.rst is the main file for the whole project.

How to contribute

We enforce everyone to write clean and explaining documentation. However, there are several rules about writing styling.

We are using doc8 to validate our docs. So, here’s the command to do it:

doc8 ./docs

This is also used in our CI process, so your build will fail if there are violations.

Useful plugins

Some sphinx plugins are not included, since they are very specific. However, they are very useful:

Further reading