BLISS Documentation¶

BLISS Documentation is furnished in various manners:

main documentation using mkdocs https://www.mkdocs.org/
- 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

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

. blissenv -d

conda activate <env_name>
cd <bliss.git directory>
pip install -e .[doc]

This installs mkdocs and dependencies (sphinx, mkdocs-graphviz, pymdown-extensions, etc.).

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> dev_documentation.md

Once you save dev_documentation.md 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 config_mynewcontroller.md

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

Example:¶

ESRF - PePU controller

Example YAML_ configuration:

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

Usage:

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

template:¶

ESRF - XXX controller

Example YAML configuration:

    plugin: bliss
    class: XXX
    module: xxx
    name: xxx
    tcp:
      url: xxx.esrf.fr

Usage: XXX

For more information, see the XXX documentation: XXX.

Doc-strings¶

GUI doc¶

examples:

Menu: Help ▶ IPython.
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): https://stackedit.io/app#

And a summary of markers: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

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

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:

hostname
myhost
cd <bliss.git directory>/doc/
mkdocs serve -a 0.0.0.0:8888

and visit http://myhost:8888 to see the documentation

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¶

Comments¶

HTML comments  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

ATTENTION !!!!

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

Info

bla bla

Abstract

bla bla

Example

just do like that

Tip

Do you known you can do… ?

Success

And voila !

to be or not to be

That’s the question.

Failure

a marche pas…

Danger

“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

Lists¶

bullet-list¶

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

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

Note

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

numbered list¶

note the space:

first
second
third

?? no nested list ?

Note

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

Links and references¶

use:

* mkdocs inner links: [Beamviewer Configuration](config_beamviewer.md).
* inner link to section: [code formatting](dev_guidelines.md#code-formatting-with-black)
* outer link: [ESRF Gitlab](https://gitlab.esrf.fr/bliss/bliss)
* outer link: https://gitlab.esrf.fr/bliss/bliss

to produce:

mkdocs inner link: Beamviewer Configuration.
mkdocs inner link with section ref: code formatting
outer link: ESRF Gitlab
outer link: https://gitlab.esrf.fr/bliss/bliss

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:

 ```bash
 <code>
 ```

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¶

Inline¶

The following effects:

italic
raw text in monospace font
bold
~~strikethrough~~
highlighted

can be obtained using such formatting:

* *italic*
* `raw text in monospace font`
* **bold**
* ~~strikethrough~~
* ==highlighted==

Python code¶

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

  ```python
  <code>
  ```

Example:

from bliss.common.axis.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
        })], [], [], [])

Info

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

YAML code¶

- controller:
    class: icepap
    host: iceid2322
    axes:
        -   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}}
$$

result:

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

images and drawings¶

ASCII¶

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

SVG¶

Code to include an existing svg file:

![Screenshot](img/ebv.svg)

result: Screenshot

Note

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

Bitmap¶

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

Screenshot

PDF¶

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

v1¶

v2¶

inline docstrings¶

Inline docstrings in BLISS code try to follow https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html style.

example:

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

    Parameters:
        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)

    Raises:
        RuntimeError

    Returns:
        None

    """

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

To build sphinx API documentation:

python setup.py build_sphinx

and to consult it, visit:

build/sphinx/html/index.html