How to write documentation

This webpage uses mkdocs. Mkdocs generates from a bunch of markdown files, and a specified template this beautiful web page.

As an author, you can just edit and create new markdown files in the docs/ of the corresponding repository: https://git.key-project.org/key/key-docs. On each commit the generation is automatically started and pushed to this URL. Therefore, you do not need to install mkdocs on your computer.

The project layout is very simple: There is a configuration file mkdocs.yml which controls the plugins and settings for the generation. And also a content folder docs/ which contains Markdown files and additionally resources.

Local setup

mkdocs is written in Python. Hence, everything you need is installable via the Python package manager (pip). For a non-root user install use either make prepare or execute the following line:

    pip install --user  mkdocs  mkdocs-material  pymdown-extensions pygments markdown-blockdiag markdown-aafigure==v201904.0004

This install all needed packages for this webpage inside $HOME/.local and after installation the mkdocs executable should be under $HOME/.local/bin/mkdocs.

serve: mkdocs serve

build: mkdocs build

Commands

Cinder Theme Specimen

Typography

Typefaces

Body Copy

You think water moves fast? You should see ice. It moves like it has a mind. Like it knows it killed the world once and got a taste for murder. After the avalanche, it took us a week to climb out. Now, I don't know exactly when we turned on each other, but I know that seven of us survived the slide... and only five made it out.

Now we took an oath, that I'm breaking now. We said we'd say it was the snow that killed the other two, but it wasn't. Nature is lethal but it doesn't hold a candle to man.

Like inline code? Here is a string for you 010101010.

Lead Body Copy

Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Duis mollis, est non commodo luctus.

Headings

All HTML headings, <h1> through <h6>, are available. .h1 through .h6 classes are also available, for when you want to match the font styling of a heading but still want your text to be displayed inline.

h1. Heading

h2. Heading

h3. Heading

h4. Heading

h5. Heading
h6. Heading

h1. Heading Secondary text

h2. Heading Secondary text

h3. Heading Secondary text

h4. Heading Secondary text

h5. Heading Secondary text
h6. Heading Secondary text

Blockquotes

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.

Someone famous in Source Title

Lists

Horizontal Description Lists

Something
This is something
SomethingElse
This is something else

Contextual Colors

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.

Code

Inline Code

This is an example of inline code #import requests

Preformatted Code Blocks with Syntax Highlighting

def request(method, url, **kwargs):
    """Constructs and sends a :class:`Request `.
    Usage::
      >>> import requests
      >>> req = requests.request('GET', 'https://httpbin.org/get')
      
    """

    # By using the 'with' statement we are sure the session is closed, thus we
    # avoid leaving sockets open which can trigger a ResourceWarning in some
    # cases, and look like a memory leak in others.
    with sessions.Session() as session:
        return session.request(method=method, url=url, **kwargs)

def get(url, params=None, **kwargs):
    r"""Sends a GET request.
    :param url: URL for the new :class:`Request` object.
    :param params: (optional) Dictionary, list of tuples or bytes to send
        in the body of the :class:`Request`.
    :param \*\*kwargs: Optional arguments that ``request`` takes.
    :return: :class:`Response ` object
    :rtype: requests.Response
    """

    kwargs.setdefault('allow_redirects', True)
    return request('get', url, params=params, **kwargs)

(Source code sample from the Python requests library, Apache License, v2.0)

Syntax highlighting support is available for and of the following languages listed on the highlightjs website. See the mkdocs "styling your docs" hljs_languages section for info on how to load languages dynamically.

Note

Include source code formatted in Github-flavored Markdown fenced code blocks with an info string that defines the supported programming language to automate syntax highlighting when your site is built.

Tables

Striped Table

# Head 1 Head 2 Head 3
1 Box 1 Box 2 Box 3
2 Box 4 Box 5 Box 6
3 Box 7 Box 8 Box 9

Bordered Table

# Head 1 Head 2 Head 3
1 Box 1 Box 2 Box 3
2 Box 4 Box 5 Box 6
3 Box 7 Box 8 Box 9

Buttons

Default Buttons

Link

Styled Buttons

Button Sizes

Block Level Buttons

Alerts

Callouts

Default Callout

This is a default callout.

Primary Callout

This is a primary callout.

Success Callout

This is a success callout.

Info Callout

This is an info callout.

Warning Callout

This is a warning callout.

Danger Callout

This is a danger callout.

Admonitions

The following admonitions are formatted like the callouts above but can be implemented in Markdown when you include the admonition Markdown extension in your mkdocs.yml file.

Add the following setting to mkdocs.yml:

markdown_extensions:
  - admonition

and then follow the instructions in the extension documentation to author admonitions in your documentation.

Cinder currently supports note, warning, and danger admonition types.

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.


# this is a note
def func(arg) {
  # notable things are in here!
  return None
}

Warning

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.


# this is a warning
def func(arg) {
  # be careful!
  return None
}

Danger

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.


# this is dangerous
def func(arg) {
  # BOOM!
  return None
}

Classical Markdown

https://markdown.de/

Headers are introduced with #. Multiple # increases the header level.

Paragraphs are separated by a blank line.

A 2nd paragraph. You can format your text: Italic, bold, and monospace.

*Italic*, **bold**, and `monospace`.

List are either introduced with * or -.

* this one
* that one
* the other one

or with numbers (the systems automatically counts):

1. first item
1. second item
1. third item
  1. first item
  2. second item
  3. third item

You can quote with > like in E-Mails.

Block quotes are written like so.

They can span multiple paragraphs, if you like.

Dashes -- (2-dash), --- (em-dash) and ... are automatically converted. Unicode or HTML fragments are also supported

Code is introduce with ```` or `````.

# Let me re-iterate ...
for i in 1 .. 10 { do-something(i) }

As you probably guessed, indented 4 spaces. By the way, instead of indenting the block, you can use delimited blocks, if you like:

import time
# Quick, count to ten!
for i in range(10):
    # (but not *too* quick)
    time.sleep(0.5)
    print i

References by [text](link): For example a website or a local doc.

size material color


9 leather brown 10 hemp canvas natural 11 glass transparent

Table: Shoes, their sizes, and what they're made of

(The above is the caption for the table.) Pandoc also supports multi-line tables:

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell
First Header Second Header
Content Cell Content Cell
Content Cell Content Cell

Images with alternative text and tooltip ![example image](example-image.jpg "An exemplary image")

KeYLogo

Markdown Extensions:

You should consult the following site for more examples:

If you do not find a construct you could also look at: PyDown extenstions directly. Extension are activated in the mkdocs.yml.

Here is a short excerpt:

Admontion

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.

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.

There are a lots of other types and keywords!

Code Highlighting

``` python
import tensorflow as tf
```

becomes

import tensorflow as tf

``` bash tab="Bash"

!/bin/bash

echo "Hello world!"

``` c tab="C"
#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
}

``` c++ tab="C++"

include

int main() { std::cout << "Hello world!" << std::endl; return 0; }

``` c# tab="C#"
using System;

class Program {
  static void Main(string[] args) {
    Console.WriteLine("Hello world!");
  }
}

Footnotes

Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]

Lorem ipsum1 dolor sit amet, consectetur adipiscing elit.2

Math

Example:

\[
\frac{n!}{k!(n-k)!} = \binom{n}{k}
\]
\frac{n!}{k!(n-k)!} = \binom{n}{k}

Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$

Lorem ipsum dolor sit amet: p(x|y) = \frac{p(y|x)p(x)}{p(y)}

Ascii figures

Currently not enabled due to a bug.

You can use asciiflow to draw ascii diagrams easily.

Shape Line Point 2 draw start x move end y Circle center radius

Block diagrams

blockdiag {
    A -> B -> C -> D;
    A -> E -> F -> G;
}

seqdiag {
    // edge label
    A -> B [label = "call"];
    A <- B [label = "return"];
    // diagonal edge
    A -> B [diagonal, label = "diagonal edge"];
    A <- B [diagonal, label = "return diagonal edge"];
    // color of edge
    A -> B [label = "colored label", color = red];
    // failed edge
    A -> B [label = "failed edge", failed];
}


  1. Lorem ipsum dolor sit amet, consectetur adipiscing elit. 

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