dev_documentation.md 10.3 KB
Newer Older
Cyril Guilloud's avatar
Cyril Guilloud committed
1
2
3
4
5
# BLISS Documentation

BLISS Documentation is furnished in various manners:

* main documentation using mkdocs https://www.mkdocs.org/
Cyril Guilloud's avatar
Cyril Guilloud committed
6
    - When adding a page, the main summary in `doc/mkdocs.yml` must be
Cyril Guilloud's avatar
Cyril Guilloud committed
7
      modified according to the new hierarchy.
Cyril Guilloud's avatar
Cyril Guilloud committed
8
9
    - As usual, merge requests are used to track and review modifications.
    - Common parts of documentation must be factorized as much as
Cyril Guilloud's avatar
Cyril Guilloud committed
10
11
12
13
14
15
      possible in order to keep a good coherency. When developing a
      new motor controller for example, the common documentation can
      be found [here](dev_write_motctrl.md) and only the specific part
      will be kept in source code.

* embeded in source code
Cyril Guilloud's avatar
Cyril Guilloud committed
16
17
    - inline comments to understand source code
    - *doc-string* after all user functions to be accessible from BLISS
Cyril Guilloud's avatar
Cyril Guilloud committed
18
19
      shell with `help(<function>)`

20
21
22
## Installing documentation requirements

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

26
!!! note "At ESRF"
27
28
    At ESRF, enter the BLISS development conda environment to install documentation requirements:
    ```bash
29
    . blissenv -d
30
    ```
31
32
33


```bash
34
35
cd <bliss.git directory>
conda install --file requirements-doc-conda.txt
36
```
37
38
39
40

This installs `mkdocs` and all dependencies.

In order to serve a local version of the documentation, start
Cyril Guilloud's avatar
Cyril Guilloud committed
41
the mkdocs server with:
42
```bash
43
44
cd <bliss.git directory>/doc/
mkdocs serve
45
46
```
And visit http://localhost:8000
47
48


Laurent Claustre's avatar
Laurent Claustre committed
49
In order to update the documentation
50
http://localhost:8000/dev_documentation.html
51
52
53
Please do the following

```bash
54
55
cd <bliss.git directory>/doc/docs
<your favorite editor> dev_documentation.md
56
57
```

58
59
Once you save **dev_documentation.md** you can see the new version
by reloading
60
http://localhost:8000/dev_documentation.html
Cyril Guilloud's avatar
Cyril Guilloud committed
61
62
63
64
65

## New controller documentation

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

Laurent Claustre's avatar
Laurent Claustre committed
66
67
Create a new file, for instance config_mynewcontroller.md

68
69
Update the master **../mkdocs.yml** file to insert the new controller
documentation with a title and the reference the .md file.
Cyril Guilloud's avatar
Cyril Guilloud committed
70

71
### Example:
72

73
**ESRF - PePU controller**
74

75
Example YAML_ configuration:
76

77
```yaml
78

79
80
81
82
83
84
85
86
	plugin: bliss
	class: PEPU
	module: pepu
	name: pepudcm2
	tcp:
	  url: pepudcm2
	template: renishaw    # optional
```
87

88
Usage:
Cyril Guilloud's avatar
Cyril Guilloud committed
89

90
91
92
```
>>> from bliss.config.static import get_config
>>> from bliss.controllers.pepu import Stream, Trigger, Signal, ChannelMode
Cyril Guilloud's avatar
Cyril Guilloud committed
93

94
>>> config = get_config()
95

96
97
>>> pepudcm2 = config.get('pepudcm2')
```
Cyril Guilloud's avatar
Cyril Guilloud committed
98

99
100
For the counter interface, see the
`PePU scan support documentation <bliss.scanning.acquisition.pepu.html>`
Cyril Guilloud's avatar
Cyril Guilloud committed
101
102


Cyril Guilloud's avatar
Cyril Guilloud committed
103
### template:
Cyril Guilloud's avatar
Cyril Guilloud committed
104

105

106
**ESRF - XXX controller**
107

108
Example YAML configuration:
109

110
```yaml
111

112
113
114
115
116
117
118
119
120
121
122
123
	plugin: bliss
	class: XXX
	module: xxx
	name: xxx
	tcp:
	  url: xxx.esrf.fr
```

Usage:
     XXX

For more information, see the XXX documentation: XXX.
124

Cyril Guilloud's avatar
Cyril Guilloud committed
125
126
127
## Doc-strings


Cyril Guilloud's avatar
Cyril Guilloud committed
128

Cyril Guilloud's avatar
Cyril Guilloud committed
129
130
131
132
133
134
135
136
137
## GUI doc

examples:

* Menu: `Help``IPython`.

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


Cyril Guilloud's avatar
Cyril Guilloud committed
138
139
140
## Markdown examples

This page can be used as example of typical markdown usage.
Cyril Guilloud's avatar
Cyril Guilloud committed
141
142
143
144
145
146

Here is an online editor to test your markdown:
https://nhnent.github.io/tui.editor/api/latest/tutorial-example01-basic.html#

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

Cyril Guilloud's avatar
Cyril Guilloud committed
147
### Documentation creation
Cyril Guilloud's avatar
Cyril Guilloud committed
148
149
150
151
152

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
153
154
    * pymdown-extensions / markdown-inline-graphviz / Markdown
* These packages are in `requirements-doc-conda.txt`
Cyril Guilloud's avatar
Cyril Guilloud committed
155

156
!!! note  "At ESRF"
157
158
    At ESRF, enter the BLISS development conda environment to install documentation requirements:
    ```bash
159
    . blissenv -d
160
    ```
Cyril Guilloud's avatar
Cyril Guilloud committed
161

162
```bash
163
164
cd <bliss.git directory>
conda install --file requirements-doc-conda.txt
165
166
167
```

* launch `mkdocs` in server mode in your conda environment:
Cyril Guilloud's avatar
Cyril Guilloud committed
168

169
```bash
170
hostname
171
myhost
172
cd <bliss.git directory>/doc/
Cyril Guilloud's avatar
Cyril Guilloud committed
173
mkdocs serve -a 0.0.0.0:8888
174
```
Cyril Guilloud's avatar
Cyril Guilloud committed
175

176
* and visit [http://myhost:8888](http://myhost:888) to see the documentation
Cyril Guilloud's avatar
Cyril Guilloud committed
177
178
179
180
181


### Level 3 title
There are 6 levels of titles.

182
!!! note  "Title of the note"
Cyril Guilloud's avatar
Cyril Guilloud committed
183
184
185
186
     Titles of levels 2 to 6 are referenced in lateral right bar.

#### Level 4 title

187
!!! note  "Title of the note"
Linus Pithan's avatar
Linus Pithan committed
188
189
    A note is made with an empty line, 3 !!!, `note` keyword and indented text.
    ```
Cyril Guilloud's avatar
Cyril Guilloud committed
190

191
    !!! note "Title of the note"
Linus Pithan's avatar
Linus Pithan committed
192
193
        A note of made with an empty line and 3 !!!
    ```
194
195


Cyril Guilloud's avatar
Cyril Guilloud committed
196
197
198
199
##### Level 5 title

###### Level 6 title

200
201
202
203
204
205
206
207

### Comments

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.

<!-- This comment will be visible in html source code. -->

208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
### emphasis blocks

There are some ways to outline information in blocks:

with admonition plugin:
https://squidfunk.github.io/mkdocs-material/extensions/admonition/

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


!!! note "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*


!!! warning "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 !

!!! question "to be or not to be"

    That's the question.

!!! failure

    a marche pas...

!!! danger

    "Use that at your own risks"

!!! quote "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


Cyril Guilloud's avatar
Cyril Guilloud committed
284
285
### Lists

Cyril Guilloud's avatar
Cyril Guilloud committed
286
287
#### bullet-list
To create a bullet-list, an empty line must be respected:
Cyril Guilloud's avatar
Cyril Guilloud committed
288
289
290

* and start 1st level lines with `* ` (star + space)
* etc.
Cyril Guilloud's avatar
Cyril Guilloud committed
291
292
    - Nested list are possible,
    - with 4 spaces to begin the 2nd level lines.
Cyril Guilloud's avatar
Cyril Guilloud committed
293
294
295
        * and 8 for 3rd level
        * etc.

Cyril Guilloud's avatar
Cyril Guilloud committed
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
!!! note
    `*` and `-` as bullet-list marker can be alternated to clearly indicate sub-lists

#### numbered list
note the space:

1. first
1. second
1. 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.

Cyril Guilloud's avatar
Cyril Guilloud committed
312

313
314
### Links and references
use:
315

316
317
318
319
320
```
* mkdocs inner links: [Beamviewer Configuration](config_beamviewer.md).
* inner links to section: [code formatting](dev_guidelines.md#code-formatting)
* outer links: [ESRF Gitlab](https://gitlab.esrf.fr/bliss/bliss)
```
321

322
to produce:
Cyril Guilloud's avatar
Cyril Guilloud committed
323
324

* mkdocs inner links: [Beamviewer Configuration](config_beamviewer.md).
Cyril Guilloud's avatar
Cyril Guilloud committed
325
* mkdocs inner links with section ref: [code formatting](dev_guidelines.md#code-formatting)
Cyril Guilloud's avatar
Cyril Guilloud committed
326
327
* outer links: [ESRF Gitlab](https://gitlab.esrf.fr/bliss/bliss)

328

Cyril Guilloud's avatar
Cyril Guilloud committed
329
### Raw text
Cyril Guilloud's avatar
Cyril Guilloud committed
330

Cyril Guilloud's avatar
Cyril Guilloud committed
331
Inline raw text is surronded by single backquotes:
Cyril Guilloud's avatar
Cyril Guilloud committed
332
333

    `raw text in monospace font`
334

Cyril Guilloud's avatar
Cyril Guilloud committed
335
336
result: `raw text in monospace font`

Cyril Guilloud's avatar
Cyril Guilloud committed
337
338
339
340
341
or triple backquotes for multi-lines text:
```
My text without any change,
but it has to be text without symbols.
```
342
343
344

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

Cyril Guilloud's avatar
Cyril Guilloud committed
346
347
348
349
350
351
line1  
line2  
line3  

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

352
353
```markdown
 ```bash
Cyril Guilloud's avatar
Cyril Guilloud committed
354
 <code>
355
 ```
356
357
358
```

Here is an example with <,> and [ in the text
Cyril Guilloud's avatar
Cyril Guilloud committed
359

360
361
362
363
364
365
366
367
```bash
% 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]
```
Cyril Guilloud's avatar
Cyril Guilloud committed
368
369


Cyril Guilloud's avatar
Cyril Guilloud committed
370
371
372
### Formated text

#### Inline
Cyril Guilloud's avatar
Cyril Guilloud committed
373
374
375
376
377
378

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



Cyril Guilloud's avatar
Cyril Guilloud committed
379
380
#### Python code

381
To specify a programing language, 3 backquotes can be used:
Cyril Guilloud's avatar
Cyril Guilloud committed
382
383
384
385
386
```
  ```python
  <code>
  ```
```
Cyril Guilloud's avatar
Cyril Guilloud committed
387

Cyril Guilloud's avatar
Cyril Guilloud committed
388
Example:
Cyril Guilloud's avatar
Cyril Guilloud committed
389
390
391
392
393
394
395
396
397
```python
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
        })], [], [], [])
```

398
399
!!! info
    With such formatting, Python code is easier to copy/paste in a shell.
Cyril Guilloud's avatar
Cyril Guilloud committed
400

Cyril Guilloud's avatar
Cyril Guilloud committed
401
#### YAML code
Cyril Guilloud's avatar
Cyril Guilloud committed
402

Cyril Guilloud's avatar
Cyril Guilloud committed
403
```yaml
Cyril Guilloud's avatar
Cyril Guilloud committed
404
405
406
407
408
409
410
411
412
- controller:
    class: icepap
    host: iceid2322
    axes:
        -   name: ts2f
            address: 4
            steps_per_unit: 1000
```

Cyril Guilloud's avatar
Cyril Guilloud committed
413
414
#### Mathematic formula

Cyril Guilloud's avatar
Cyril Guilloud committed
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
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}}
$$


Cyril Guilloud's avatar
Cyril Guilloud committed
430
431
432
### images and drawings

#### SVG
Cyril Guilloud's avatar
Cyril Guilloud committed
433
434
435

Code to include an existing svg file:

Linus Pithan's avatar
Linus Pithan committed
436
    ![Screenshot](img/ebv.svg)
Cyril Guilloud's avatar
Cyril Guilloud committed
437
438

result:
Linus Pithan's avatar
Linus Pithan committed
439
![Screenshot](img/ebv.svg)
Cyril Guilloud's avatar
Cyril Guilloud committed
440

441
!!! note
442
    To avoid fonts problems with svg files, texts can be converted to
443
    pathes. Select all and use Shift-Ctrl-C in Inkscape for example.
Cyril Guilloud's avatar
Cyril Guilloud committed
444

Cyril Guilloud's avatar
Cyril Guilloud committed
445
#### Bitmap
Cyril Guilloud's avatar
Cyril Guilloud committed
446
447
448
449

PNG, SVG or GIF files can be used

![Screenshot](img/CT2/p201.png)
Cyril Guilloud's avatar
Cyril Guilloud committed
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501



## inline docstrings

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

example:
```python
@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
```