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
We are using
sphinx as a documentation builder.
sphinx.ext.napoleon to write
pretty docstrings inside the source code.
We also use
sphinx_autodoc_typehints to inject type annotations into docs.
pyproject.toml as the source of truth for our deps.
All docs-related packages are stored under
To install them use:
poetry install -E docs
We use a clear structure for this documentation.
pages/templatecontains 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/projectcontains everything related to the project itself. Usage examples, an auto-generated documentation from your source code, configuration, business, and project goals
documentscontains different non-sphinx documents like
docfiles, spreadsheets, and mockups
Please, do not mix it up.
How to structure project docs¶
It is a good practice to write a single
for every single
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.
django application we tend to create
a file called
index.rst which is considered
the main file for the application.
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:
This is also used in our CI process, so your build will fail if there are violations.
sphinx plugins are not included, since they are very specific.
However, they are very useful:
sphinxcontrib-mermaid - sphinx plugin to create general flowcharts, sequence and gantt diagrams
sphinxcontrib-plantuml - sphinx plugin to create UML diagrams
nbsphinx - sphinx plugin to embed
ipythonnotebooks into your docs