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 and pip to be installed. 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.

How to install as a user (recommended)

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

pip install --user mkdocs
pip install --user mkdocs-material
pip install --user pyembed-markdown

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

pip install mkdocs
pip install mkdocs-material
pip install pyembed-markdown

How to upgrade (as a user)

Make sure you are using mkdocs version 0.17.2+.

pip install -U --user mkdocs
pip install -U --user mkdocs-material
pip install -U --user pyembed-markdown

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 with the docs/ directory.

Warning

If you are renaming or creating new markdown files (*.md extension), you should also update the pages configuration section in mkdocs.yml. Otherwise the update will not be reloaded in your browser. This is a known limitation of mkdocs that will be addressed in future releases. Until then, there is a small shell script that updates the pages section automatically. However, it only works on Unix systems.

# refreshes the pages section
./fix-mkdocs-pages.sh mkdocs.yml

Deployment

Using the command mkdocs gh-deploy we can 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.

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 create a pull request instead of directly deploying the built docs to the gh-pages branch.

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 two-level 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 underscores _. This allows for easier refactoring because spaces are transformed to %20 in markdown.

Formatting examples

Sectioning, Headings and Table of Contents
# Chapter

## Section

### Subsection
Footnotes
Some text with a footnote[^1]

[^1]: 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 folder (path/to/ABC). This way, different topics are better encapsulated.

Figures with caption (sort of)

With the following hack, you can create a nice looking caption rendered under a figure.

![](path/to/image.svg)
> **Figure:**
> Here comes some multi-line caption.
> Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Figure: Here comes some multi-line caption. 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 
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">
   [![](scenarios/img/scen-smartcity.svg) Smart City](scenarios/01_city)
 </div>