Documentation

This is the most important factor, in my opinion. What is it worth a code with all code quality metrics possible, but that I do not even know how to run it? If I do not know what is it purpose? If I do not know how to use it?

The template enforces documentation in two ways:

• Prospector: if there are missing docstrings, or wrong docstrings formats, for example, Prospector will indicate them.
• Sphinx: if there are broken references in docstrings, for example, Sphinx will indicate them.

But this is not enough to assure a good documentation. To assure the documentation is good, it is needed people to read it and check if it answers the previous questions.

A picture is worth a thousand 1️⃣0️⃣0️⃣0️⃣ words

When possible, use images, gifs and emojis 😃 to facilitate the understanding of who is reading the documentation. Check this FastAPI awesome example.

How to contribute?

It is also extremely important to write the guidelines on how to contribute to a project (even if it not an open source one). People do want to help, but if they do not feel they can help, they probably will not.

Configuration

https://github.com/mateusoliveira43/python-project-template/blob/main/docs/conf.py#L1-L32

Running

The command dev doc --check (an alias to sphinx-apidoc --force -q --module-first --private --output-dir docs/modules source && sphinx-build -WTvna docs public) will check the generation of project's documentation.

The command dev doc (an alias to sphinx-apidoc --force -q --module-first --private --output-dir docs/modules source && sphinx-build -vna docs public) will generate the project's documentation.