Skip to content

Documentation Howto

We use mkdocs for documenting the project. The goal is to make the documentation process as simple as possible, to allow versioning and to use pull requests for text reviews. I should edit the docs locally, preview it in a browser and then suggest a pull request.

The amount of formatting elements is deliberately small. Apart from wiki, we try to keep each page self contained and to minimize interlinking between pages because it only complicates reading of the docs.

The documentation is written as a set of Markdown files within the docs/ directory and after deployment available as a static website: Docs Website.

Before building the docs

First of all, you need python 3 and pip3 to be installed. (On some Linux distros, you need to use pip3 instead of pip)

Using pip, you need to install the following packages:

  • mkdocs : Provides the executable command mkdocs.
  • mkdocs-material : A material design theme. See also this page.
  • pyembed-markdown : A markdown extension that allows for embedding Youtube videos in documents. See also this page.
  • mkdocs-awesome-pages-plugin : This plugin automatically generates the pages section from directory structure. (For more info see this github repository)

How to install as a user (recommended)

You can install the packages locally as a user into ~/.local/

pip3 install --user mkdocs
pip3 install --user mkdocs-material
pip3 install --user pyembed-markdown
pip3 install --user mkdocs-awesome-pages-plugin

How to install system-wide as root (not recommended)

pip3 install mkdocs
pip3 install mkdocs-material
pip3 install pyembed-markdown
pip3 install mkdocs-awesome-pages-plugin

How to upgrade (as a user)

Make sure you are using mkdocs version 0.17.2+.

pip3 install -U --user mkdocs
pip3 install -U --user mkdocs-material
pip3 install -U --user pyembed-markdown
pip3 install -U --user mkdocs-awesome-pages-plugin

Since we use the markdown format, you can use any plain text editor. However, we suggest to use IntelliJ IDEA with the Markdown Support plugin (both are free) which gives you:

  • syntax highlighting
  • path completion of links such as image file names
  • refactoring, which is handy when renaming markdown files which are liked from other files
  • fancy search
  • outline of the document structure
  • automated simplified preview (which is not that important due to the mkdocs hot-reload)

How to edit

Before editing the documentation, start the live-reloading docs server using mkdocs serve within the project root directory. Then, open the page http://127.0.0.1:8000 in your browser and watch your edits being reloaded automatically.

1
mkdocs serve
INFO    -  Building documentation... 
INFO    -  Cleaning site directory 
[I 171024 15:03:51 server:283] Serving on http://127.0.0.1:8000
[I 171024 15:03:51 handlers:60] Start watching changes

You can now edit the markdown documents within the docs/ directory.

Deployment

Warning

This operation is relevant only to the administrators of the biggis-docs repository. As a regular contributor, you should only preview your local changes and push them to the master branch or through pull request instead of directly deploying the built docs to the gh-pagesbranch.

The deployment is about building the HTML version out of the markdown sources from the master git branch and and pushing the generated content to the gh-pages branch. Github then makes this new version available online.

The responsible person then uses the command mkdocs gh-deploy to generate a static Docs Website and deploy it automatically as a github page (served from gh-pages branch).

Info

The newly deployed version appears after few seconds.

Documentation layout

mkdocs.yml    # The configuration file.
docs/
  index.md    # The documentation homepage.
  ...         # Other markdown pages, images and other files.

For the sake of simplicity, we use the following hierarchy inside docs/:

  • Level 1 : areas (directories) that appear in the main menu.
  • Level 2 : pages (markdown files) that appear in the left side bar.
  • Level 3 : headings (H1, H2, ...) that appear in the table of contents on the right

Warning

Do not use spaces in file names. Replace them with dashes - (or alternatively with underscores _). This allows for easier refactoring because spaces are usually transformed to %20 in markdown which looks weird.

Formatting examples

Sectioning, Headings and Table of Contents
# Chapter

## Section

### Subsection

Table of contents is generated automatically from the document structure.

Footnotes
Some text with a footnote[^LABEL]

[^LABEL]: Text of the footnote

See also https://squidfunk.github.io/mkdocs-material/extensions/footnotes/

Citations, Notes and Admonition
!!! cite
    Here comes the citation including authors, title, year, doi, url ...

Cite

Here comes the citation including authors, title, year, doi, url ...


!!! note
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.


For more options see https://squidfunk.github.io/mkdocs-material/extensions/admonition/

Collapsible blocks
??? "Phasellus posuere in sem ut cursus"
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
Phasellus posuere in sem ut cursus

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

For more information see https://facelessuser.github.io/pymdown-extensions/extensions/details/

Images

You can include images into the documentation in the following format:

  • SVG (scalable vectors).
  • JPG (photos)
  • PNG (raster graphics)

In contrast to scientific papers, it is not possible to create references to numbered figures in markdown.

![Image "alt" description](path/to/image.svg)

Sample image

See also http://www.mkdocs.org/user-guide/writing-your-docs/#images-and-media

Note

When editing a file e.g. path/to/ABC.md, store all related images in the same folder (path/to/ABC). This way, different topics are better encapsulated.

Figures with caption (on top)

You can create images with a nice looking caption and additional description.

!!! info "Figure: Here comes a single line title"
    ![](path/to/image.svg)

    Here comes some additional multi-line text.
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    Morbi et iaculis mi, ut interdum risus. Nulla facilisis viverra felis tincidunt sagittis.

Figure: Here comes a single line title

Here comes some additional multi-line text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi et iaculis mi, ut interdum risus. Nulla facilisis viverra felis tincidunt sagittis.

Tables
First Header | Second Header | Third Header
------------ | ------------- | ------------
Content Cell | Content Cell  | Content Cell
Content Cell | Content Cell  | Content Cell
First HeaderSecond HeaderThird Header
Content CellContent CellContent Cell
Content CellContent CellContent Cell

See also http://www.mkdocs.org/user-guide/writing-your-docs/#tables

Tables with alignment
Left         | Center        | Right
---          |:--            |--:
Content Cell | Content Cell  | Content Cell
Content Cell | Content Cell  | Content Cell
LeftCenterRight
Content CellContent CellContent Cell
Content CellContent CellContent Cell

See also http://www.mkdocs.org/user-guide/writing-your-docs/#tables

Mathematical Formulas

Formula are generated using MathJax, which is similar to LaTeX. See also this quick reference.

$$
\frac{n!}{k!(n-k)!} = \binom{n}{k}
$$
\frac{n!}{k!(n-k)!} = \binom{n}{k}
Source Code with Code Highlighting

Code can be displayed inline like this:

`print 1+{variable}`

Or it can be displayed in a code block with optional syntax highlighting if the language is specified.

```python
def my_function():
    "just a test"
    print 8/2 
```
def my_function():
    "just a test"
    print 8/2 

Other useful langauge codes are:

  • sh : source code written in shell script
  • console: commands written to console, e.g.: $ cat /dev/urandom
  • json: data in JSON format
  • javascript: JavaScript source code
Smart Symbols
Some smart symbols: -->,  <--, 1st, 2nd, 1/4

Some smart symbols: →, ←, 1st, 2nd, ¼

See also https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/

Sequence diagrams
```sequence
Title: Example sequence diagram
A->B: Sync call
B-->A: Sync return
A->C: Another sync call
C->>D: Async call
D-->>C: Async return
```
Title: Example sequence diagram
A->B: Sync call
B-->A: Sync return
A->C: Another sync call
C->>D: Async call
D-->>C: Async return
Embedded Youtube Videos
[!embed](https://www.youtube.com/watch?v=QQKVzZpXTpQ)

For more information see https://pyembed.github.io/usage/markdown/

HTML (please only in special cases)

In special cases, you can also use raw HTML in your document.

 <style>.special img {height:32px; vertical-align:middle}</style>
 <div class="special">
   [![](https://www.gstatic.com/webp/gallery3/5.png)](https://developers.google.com/speed/webp/gallery2)
   Click on this icon
 </div>

Click on this icon