Contributing to the Documentation

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

Branch strategy

The documentation repository has two branches:

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:

Danger

Very dangerous operation!

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!.