Contributing: Docs#


This project uses poetry >= 1.2 to manage it's dependencies. Please checkout the official instructions to setup poetry on your system.

$ git clone && cd docs
$ poetry install --no-root

We also use a poetry plugin called poethepoet to aid in managing our frequently run tasks.

$ poetry self add 'poethepoet[poetry_plugin]'

Our docs are managed by mudkip, a wrapper on the popular sphinx project.

$ poe dev

This will launch a development web server on localhost:5500 which loads the locally built docs. The process will also watch the docs folder for any changes and will trigger a rebuild which reloads your page with your changes implemented.

Generating API Docs#

Our API documentation is generated from docstrings directly from our source code. To generate the files, run the following within the root of the project:

$ poe generate-api-docs


Our docs are primarily written in markdown, with some extra flavor added via the MyST plugin. This makes it easier to start writing content, while being able to sprinkle in fancier content!

Additionally, we also use the follow extensions:

  • Colon Fences

    • Makes using ":::" and "::::" instead of pure "```" and "````" which is nicer to use within markdown files.

    • We prefer using "::::" for grids and groupings while "```" for simple cards and dropdowns.

  • Substitution

    • Allows the use of simple Jinja2 substitutions within YAML frontmatter.

  • Sphinx Design

    • This extension adds several useful cards, grids, icons, and dropdowns to make the documentation look nicer.