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 also use sphinx_autodoc_typehints to inject type annotations into docs.

We also using two sources of truth for the dependencies here:

  • docs/requirements.txt
  • Pipfile

Why? Because ReadTheDocs we are using for this template (only for original Github repo) does only support traditional requirements.txt.

Structure

We use 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/documents contains different non-sphinx documents like doc files, spreedsheets, and mockups
  • _pages/project contains everything related to the project itself. Usage examples, autogenerated documentation form your source code, configuration, business and project goals

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 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 app.rst which is considered the main fail 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.