Writing Documentation🔗
The source files are in the main github repository, in the docs folder.
They are simple Markdown files, that you can edit in any text editor of your choice.
The local development and test is made using mkdocs. This allows you to test your documentation changes for styling issues and see what it will look like once rendered.
After installing mkdocs, you can use mkdocs serve in the main folder of this repository to start the development server.
If you want to include pictures and diagrams in the documentation, please set the pictures in a dedicated folder to the name of the page you are creating (for example, if your page is named expert_setup.md, please put all the related pictures in the docs/expert_setup/ folder). Each picture should be named with a simple yet descriptive name, using jpg or png format if possible. Try to limit the size of the file by limiting the resolution to what is necessary for the picture to be clear on screen.
Contributions should be made by creating pull requests on Github directly.
Extensions available🔗
In addition to the common markdown syntax, several extensions are activated. If you want more information on any of them, please follow the linked guides.
- SmartyPants: Converts ASCII dashes, quotes and ellipses to their HTML entity equivalents.
- Sane Lists: Alters the behavior of the Markdown List syntax to be less surprising.
- Admonition: Adds rST-style admonitions to Markdown documents.
- Table of contents: Generates a Table of Contents from a Markdown document and adds it into the resulting HTML document.
- Metadata: Adds a syntax for defining meta-data about a document.
- Tables: Adds the ability to create tables in Markdown documents.
- Fenced Code Blocks: Adds a secondary way to define code blocks.