Documentation

README

The repository contains a 📝 README.rst file with basic information.
It gives a short introduction to the project and links to other relevant files.

Changelog

The 📝 CHANGELOG.md is a record of all notable changes made to a project.
It is structured by each release and divided by additions, changes, and removals.

MkDocs

MkDocs is a fast and simple static site generator that is used for documentation.
The source files are written in Markdown, and configured with 📝 mkdocs.yml.
Material theme enables additional features and an elegant design.

Install

Install the required packages in a python environment.
💻 pip install mkdocs Install MkDocs
💻 pip install mkdocs-material Install the material theme

Build

Generate the documentation locally.
💻 mkdocs serve Start the local live version of the documentation
💻 mkdocs build Create a folder site with the documentation

Publish

Manually

Publish documentation on GitHub Pages.
💻 mkdocs gh-deploy Manually deploys the documentation files

Manually deploy documentation

This command overrides all manually deployed versions (mike).

GitHub Action

🐙 Deploy the documentation with GitHub Actions.
The file 📝 .github\workflows\documentation.yml creates an automated GitHub workflow.
It is configured to be pushed to the branch gh-page and then deployed online.
A commit on the develop branch starts the workflow.

Mike

The package mike is used to deploy multiple versions of the documentation.
💻 pip install mike Install mike
💻 mike deploy --push --update-aliases 0.1 latest Deploys the latest version
💻 mike set-default --push latest Set the default version to latest
💻 mike deploy develop --push Deploys the develop branch

Mike Versions

It is recommended to use only the Minor Versions (for example 0.1) and exclude the Patch Version (for example 0.1.1)!

Other useful commands are:
💻 mike serve Test mike on http://localhost:8000
💻 mike list List all versions
💻 mike retitle 1.0.0 1.0.1 --push Rename a version
💻 mike delete 0.1 --push Deletes a specific versions
💻 mike delete --all --push Deletes all versions

When adding older versions, load the Git Tags used for the releases:
💠 git checkout v0.1.1
💻 mike deploy 0.1 --push Deploys the old version 0.1

When building mike locally, the branch gh-pages is modified locally.
💻 error: gh-pages is unrelated to origin/gh-pages
💠 git branch -D gh-pages Delete the local documentation branch

mkdocstrings

mkdocstrings generates automatic documentation (autodocs) from Google style docstrings.
💻 pip install mkdocstrings Install mkdocstrings

Used Icons

🐙 GitHub | 💠 git | 📝 File | 💻 Command Line