Documentation

This template does not include a documentation setup, but it is very important for most projects (at least it should be) to have a documentation site, especially if you are not working alone. Here are the options I would suggest for setting up a documentation, recently I tend to favor the first one.

Mkdocs with the Material theme
Sphinx with the Furo theme

There is a chance that in the future I will include the docs directly in the template but for now here is a quick guide to configure mkdocs with the material theme:

Installation and configurations¶

Copy the configuration below into your pyproject.toml file under the [tool.poetry.dependencies] section.

[tool.poetry.group.docs]
optional = true

[tool.poetry.group.docs.dependencies]
mkdocs = "^1.4.2"
mkdocs-material = "^8.5.10"
mkdocs-material-extensions = "^1.1.1"
mkdocs-include-markdown-plugin = "3.9.1"

Install the new dependencies.

poetry install --with docs

Create your new mkdocs site.

1	`mkdocs new .`

Update the mkdocs.yml file to specify the material theme, your configuration should look like this:

site_name: My Docs # change this to the name of your project
theme:
  name: material

Run the documentation site locally

1	`mkdocs serve`

If you noticed, the dependencies added above via the section [tool.poetry.group.docs.dependencies] include more than just mkdocs and the material theme, specifically :

mkdocs-material-extensions: Markdown extension resources for MkDocs for Material
mkdocs-include-markdown-plugin: Include other markdown files in your mkdocs site

For a complete example of how I configure them in projects, see this configuration file.

Deploy your documentation¶

Mkdocs can turn your documentation into a static site that you can host anywhere, netlify, github pages, etc. To build your site, run the command below and you will have a new site directory at the root of your project:

1	`mkdocs build`

This folder contains everything that is necessary to deploy your static site.

If you choose the github pages route, you can automate the process with github actions, the official mkdocs-material documentation explains how to do it. To use github actions, you will probably need a requirements.txt file, you can generate one with only what is needed to build the docs with the command below.

poetry export -f requirements.txt --output docs/requirements.txt --without-hashes --only docs

Read the mkdocs and mkdocs-material docs for more advanced configurations and details on what is possible.