Contributing to the Documentation

The Phootwork documentation site is written in markdown and built with MkDocs.

Branch strategy

The documentation repository has two branches:

• mkdocs contains the markdown documentation. You should work on this branch if you want to contribute and you should submit here your pull requests.
• master contains the site compiled by Mkdocs. This branch is handled only by our Github Actions bot. No pull request will be merged on it.

Clone and Install

1. Fork and clone the documentation repository
2. Install MkDocs
3. Install Cinder theme by running: pip install mkdocs-cinder
4. Install fontawesome-markdown extension by running: pip install https://github.com/bmcorser/fontawesome-markdown/archive/master.zip

Markdown flavour

MkDocs uses Python-Markdown with some extensions active by default. It supports the standard markdown, markdown-extra and some of the Github-flavoured markdown features. You can find detailed information on https://www.mkdocs.org/user-guide/writing-your-docs/#writing-with-markdown.

In Phootwork environment, we active also admonition and fontawesome-markdown.

Admonition

admonition extension helps to write beautiful notes or warnings or other (see the official documentation) with a syntax like the following:

!!! Danger
    Very dangerous operation!

which translates into the following:

Fontawesome

fontawesome-markdown extension allow to include Fontawesome icons in any part of the documentation, via a simple notation: :icon-type icon:. In example:

    _I :fas fa-heart: phootwork!_

translates into: I phootwork!.