How to write documentation

The Gist

Documentation is written in Markdown format, on the attached repository. To add new page to documentation, create a new file in directory tree under docs/ directory, inside it top level folders will be treated as content roots, and have separte tabs. The filename should be descriptive to prevent confusion, document name (shown in the sidebar) is taken from the header of the file.

After modifying the docs open a pull request to the repository. The changes will be reviewed and merged, and the CI/CD pipeline will automatically build the documentation and deploy new version.

Technology

The documentation is built using MkDocs, with Material theme. The source code is written in Markdown, which is a lightweight markup language with plain text formatting syntax.

Markdown

Markdown is a simple way to format text that can be converted to HTML. It uses special characters and symbols to indicate formatting, such as headings, lists, links, and images. MkDocs supports a python-markdown parser, you can find the full documentation on Python Markdown documentation.

Markdown Extensions

On top of the standard Markdown syntax, we support a range of functionality provided by PyMdown extensions. These extensions add features like tables, footnotes & notes, better code blocks and emphasis, and more. You can find full list of functionalities and how to use them in the PyMdown Extensions documentation.

On top of what's provided by PyMdown some functionality is also provided directly by MkDocs Material theme. This includes things like admonitions, tabs, and more. You can find the full list of features in the MkDocs Material reference.