Contributing to the Docs

The following tools are recommended to have installed to contribute to the docs:

Note

The docs website is generated with MkDocs which is a static site generator.

Admonitions (like this one) are written as GitHub admonitions which the GitHub Admonitions for MkDocs plugin then converts into MkDocs admonitions. This allows the admonitions in the docs to be viewable in GitHub and in website form.

Install MkDocs and the GitHub Admonition for MkDocs plugin as Python packages with your Python package manager of choice in your Python (v)env of choice. The following command uses pip to install them in your default Python (v)env:

pip install mkdocs mkdocs-github-admonitions-plugin

Working with MkDocs

Check out MkDocs' Getting Started and User Guide pages to get you up to speed on how to add new pages and have them show up on the nav bar, seeing your changes on your local browser and changing the MkDocs configuration to make these docs better!

Deploying the Docs

To deploy the docs to the GitHub Pages site execute the command:

mkdocs gh-deploy

Docs Guidelines

Admonitions (aka Alerts)

Admonitions must follow the GitHub admonition style as specified in the Alerts section of the GitHub docs.