Skip to content

This Documentation

Mkdocs with Material Theme is used to generate this documentation. Mkdocs is a CLI application made with Python and can be installed using pip.

How to use Mkdocs

  1. Install Python3 and pip. If you are on Windows be sure in the installation wizard to check the option to add python to the environment vars of your system.
  2. Execute pip install mkdocs
  3. Execute mkdocs -V, version should be >= 1.1
  4. Install Material Theme pip install mkdocs-material
  5. Move cd to the root directory of rhomb.iot
  6. Run the compiler with mkdocs serve

The command mkdocs serve will keep the session terminal open and create a web server on localhost:8000, open your browser to visit it. You can edit the documentation while the server is running and the browser will reload automatically with the changes.

Build docs

Before launching a final release the docs will be built inside a directory, like a static website. It can be uploaded to any web sever to visit online.

Build command: mkdocs build

How to write docs

The navigation menu is built automatically using the configuration of mkdocs.yml on the root folder. If you need to add a new link to the menu, first create the .md file inside the directory docs and then add the corresponding entry in the mkdocs.yml file.

Some markdown extensions have been installed.

Write step-by-step guides

Write your articles as step-by-step guides whenever possible. You can write an HTML tag to generate special bullet numbers with paragraph titles.

Example:

<div class="step-count1" markdown=1>

### Start with this

This is the description to start the job

### Continue with this

This is the next step

<div class="step-count2" markdown=1>

#### A sub task

This is a task of the point 2.

</div>

</div>

It is important the <div class="step-count1" markdown=1>, step-count1 (for ### headers) is a variable and step-count2 (for #### headers) is a second variable for sub sections

Result:

Start with this

This is the description to start the job

Continue with this

This is the next step

A sub task

This is a task of the point 2.

Highlight Code

Use ```C to add a piece of code with color highlight

uint8_t emit(uint8_t *eventNames, size_t len, uint8_t param) {
  for (unsigned int i = 0; i < len; i++) {
    uint8_t callbackErr = emit(eventNames[i], param);
    if (callbackErr > 0) {
      return callbackErr;
    }
  }

  return 0;
}

Use Emoticons

Add emoticons using short names like :heart: = ❤

For a full list of emoticons, open this file with VS Code and use the command Format Code to prettify and search codes with Ctrl+F.

All short codes starts and end with :

Use Alert boxes

Emphasize your more important sentences with alert boxes:

!!! note
    Inform about some thing important or interesting with a **note**.

Note

Inform about some thing important or interesting with a note.

Also...

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.

Question

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.

Success

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.

Tip

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.

See more at admonition plugin for Markdown.

See also all the markdown extension on Material for MkDocs site

Comments