Skip to content

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.

Documentation with 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 mkdocs#

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.

Versioning with Mike#

The package mike is used to deploy multiple versions of the documentation.
💻 pip install mike Install mike
💻 mike deploy --push --update-aliases 1.0 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

Only use the Minor Versions (1.1) and exclude the Patch Version (1.1.1)!

When adding older versions, load the Git Tags used for the releases:
💠 git checkout v1.0.0
💻 mike deploy 1.0 --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

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

Docstrings with mkdocstrings#

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

Used Icons

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