Skip to content

BLISS Documentation

BLISS Documentation is furnished in various manners:

  • main documentation using mkdocs

    • When adding a page, the main summary in doc/mkdocs.yml must be modified according to the new hierarchy.
    • As usual, merge requests are used to track and review modifications.
    • Common parts of documentation must be factorized as much as possible in order to keep a good coherency. When developing a new motor controller for example, the common documentation can be found here and only the specific part will be kept in source code.
  • embeded in source code

    • inline comments to understand source code
    • doc-string after all user functions to be accessible from BLISS shell with help(<function>)

Installing documentation requirements

In order to be able to test documentation on a PC where BLISS is installed, the documentation requirements need to be installed in a conda environment.


At ESRF, enter the BLISS development conda environment to install documentation requirements:

. blissenv -d

cd <bliss.git directory>
conda install --file requirements-doc.txt

This installs mkdocs and all dependencies.

In order to serve a local version of the documentation, start the mkdocs server with:

cd <bliss.git directory>/doc/
mkdocs serve
And visit http://localhost:8000

In order to update the documentation http://localhost:8000/dev_documentation.html Please do the following

cd <bliss.git directory>/doc/docs
<your favorite editor>

Once you save you can see the new version by reloading http://localhost:8000/dev_documentation.html

New controller documentation

What to include in code / What to put in mkdoc ???

Create a new file, for instance

Update the master ../mkdocs.yml file to insert the new controller documentation with a title and the reference the .md file.


ESRF - PePU controller

Example YAML_ configuration:

    plugin: bliss
    class: PEPU
    module: pepu
    name: pepudcm2
      url: pepudcm2
    template: renishaw    # optional


>>> from bliss.config.static import get_config
>>> from bliss.controllers.pepu import Stream, Trigger, Signal, ChannelMode

>>> config = get_config()

>>> pepudcm2 = config.get('pepudcm2')

For the counter interface, see the PePU scan support documentation <bliss.scanning.acquisition.pepu.html>


ESRF - XXX controller

Example YAML configuration:

    plugin: bliss
    class: XXX
    module: xxx
    name: xxx

Usage: XXX

For more information, see the XXX documentation: XXX.


GUI doc


  • Menu: HelpIPython.

  • some symbols: 🗹 ✅ ❌ ❓ 🔴 🔶 □ 🗹 𝚫t µ → ⟶ 🡆 ← ↑ → ↓

Markdown examples

This page can be used as example of typical markdown usage.

Here is an online editor to test your markdown (! mermaid extension is not yet available in bliss doc):

And a summary of markers:

Documentation creation

To easily view the result of your writing, using a local rendering:

  • Create or use a conda environment with good packages installed:
    • sphinx / graphviz / pygments / mkdocs / mkdocs-material
    • pymdown-extensions / mkdocs-graphviz / Markdown
  • These packages are in requirements-doc.txt


At ESRF, enter the BLISS development conda environment to install documentation requirements:

. blissenv -d

cd <bliss.git directory>
conda install --file requirements-doc.txt
  • launch mkdocs in server mode in your conda environment:
cd <bliss.git directory>/doc/
mkdocs serve -a

Level 3 title

There are 6 levels of titles.

Title of the note

Titles of levels 2 to 6 are referenced in lateral right bar.

Level 4 title

Title of the note

A note is made with an empty line, 3 !!!, note keyword and indented text.

!!! note "Title of the note"
    A note of made with an empty line and 3 !!!

Level 5 title
Level 6 title


HTML comments <!-- Bla Bla Bla. --> can be used in .md files. They will be inserted in html doc but will not be displayed in documentation web page.

emphasis blocks

There are some ways to outline information in blocks:

  • note
  • info / todo
  • example / snippet
  • warning
  • abstract / summary / tldr
  • tip / hint / important
  • success / check / done
  • question / help / faq
  • failure / fail / missing
  • danger / error
  • bug
  • quote / cite

This is a note

« Au contraire, il est impossible de partager soit un cube en deux cubes, soit un bicarré en deux bicarrés, soit en général une puissance quelconque supérieure au carré en deux puissances de même degré : j’en ai découvert une démonstration véritablement merveilleuse que cette marge est trop étroite pour contenir. » Pierre de Fermat


“Beware the ides of March.” ― William Shakespeare, Julius Caesar


bla bla


bla bla


just do like that


Do you known you can do… ?


And voila !

to be or not to be

That’s the question.


a marche pas…


“Use that at your own risks”

Quote of the day

People think that computer science is the art of geniuses but the actual reality is the opposite, just many people doing things that build on eachother, like a wall of mini stones.

Donald Knuth



To create a bullet-list, an empty line must be respected:

  • and start 1st level lines with * (star + space)
  • etc.
    • Nested list are possible,
    • with 4 spaces to begin the 2nd level lines.
      • and 8 for 3rd level
      • etc.


* and - as bullet-list marker can be alternated to clearly indicate sub-lists

numbered list

note the space:

  1. first
  2. second
  3. third

?? no nested list ?


Advantage of a numbered list well formated is to be easily selectable for copy-past items without copying the numbers.


* mkdocs inner links: [Beamviewer Configuration](
* inner links to section: [code formatting](
* outer links: [ESRF Gitlab](

to produce:

!!!note: Take care to - and lower case in sections reference.

Raw text

Inline raw text is surronded by single backquotes:

`raw text in monospace font`

result: raw text in monospace font

or triple backquotes for multi-lines text:

My text without any change,
but it has to be text without symbols.

In case you want to have a line break just insert two spaces at the end of the line, like this:

line1 line2 line3

A bash command line is surronded by triple backquotes ` followed by bash:


Here is an example with <,> and [ in the text

% bliss -h
Usage: bliss [-l | --log-level=<log_level>] [-s <name> | --session=<name>]
       bliss [-v | --version]
       bliss [-c <name> | --create=<name>]
       bliss [-d <name> | --delete=<name>]
       bliss [-h | --help]

Formated text


There are many formating marker to write text in italic or raw text in monospace font or bold or strikethrough

Python code

To specify a programing language, 3 backquotes can be used:



from bliss.common.axis import Axis
from bliss.controllers.motors import icepap
iceid2322 = icepap.Icepap("iceid2322", {"host": "iceid2322"},
    [("mbv4mot", Axis, { "address":1,"steps_per_unit":817,
    "velocity": 0.3, "acceleration": 3
        })], [], [], [])


With such formatting, Python code is easier to copy/paste in a shell.

YAML code

- controller:
    class: icepap
    host: iceid2322
        -   name: ts2f
            address: 4
            steps_per_unit: 1000

Mathematic formula

Nice formula can be integrated using Latex syntax:

Example of code for cubic crystal diffraction:

d = \frac{a}{\sqrt{h^2+k^2+l^2}}


d = \frac{a}{\sqrt{h^2+k^2+l^2}}

images and drawings


  └── timer
       ├── simulation_diode_sampling_controller
       ├── simulation_diode_sampling_controller
       └── simulation_diode_sampling_controller


Code to include an existing svg file:


result: Screenshot


To avoid fonts problems with svg files, texts can be converted to pathes. Select all and use Shift-Ctrl-C in Inkscape for example.


PNG, SVG, JPG / JPEG or GIF files can be used.



NB: hummm better use png images. see doc/docs/img/comm/Makefile

example: inkscape serial_hierarchy.svg -e serial_hierarchy.png --without-gui --export-width=1000



inline docstrings

Inline docstrings in BLISS code try to follow style.


def move(self, user_target_pos, wait=True, relative=False, polling_time=None):
    Move axis to the given absolute/relative position

        user_target_pos: float
            Destination (user units)
        wait : bool, optional
            Wait or not for end of motion
        relative : bool
            False if *user_target_pos* is given in absolute position or True if it is given in relative position
        polling_time : float
            Motion loop polling time (seconds)




Keywords: * Parameters * Raises * Returns * Notes * Attributes

To build sphinx API documentation:

python build_sphinx

and to consult it, visit: