dev_documentation.md 10.3 KB
 Cyril Guilloud committed Nov 22, 2018 1 2 3 4 5 # BLISS Documentation BLISS Documentation is furnished in various manners: * main documentation using mkdocs https://www.mkdocs.org/  Cyril Guilloud committed Feb 12, 2020 6  - When adding a page, the main summary in doc/mkdocs.yml must be  Cyril Guilloud committed Nov 22, 2018 7  modified according to the new hierarchy.  Cyril Guilloud committed Feb 12, 2020 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 committed Nov 22, 2018 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 committed Feb 12, 2020 16 17  - inline comments to understand source code - *doc-string* after all user functions to be accessible from BLISS  Cyril Guilloud committed Nov 22, 2018 18 19  shell with help()  Matias Guijarro committed Feb 14, 2019 20 21 22 ## Installing documentation requirements In order to be able to test documentation on a PC where BLISS is  Cyril Guilloud committed May 27, 2019 23 installed, the documentation requirements need to be installed  Staffan Ohlsson committed Apr 03, 2019 24 in a conda environment.  Matias Guijarro committed Feb 14, 2019 25   Cyril Guilloud committed Jun 18, 2019 26 !!! note "At ESRF"  Staffan Ohlsson committed Apr 08, 2019 27 28  At ESRF, enter the BLISS development conda environment to install documentation requirements: bash  Matias Guijarro committed Oct 08, 2019 29  . blissenv -d  Staffan Ohlsson committed Apr 08, 2019 30    Staffan Ohlsson committed Apr 03, 2019 31 32 33  bash  Matias Guijarro committed Oct 08, 2019 34 35 cd conda install --file requirements-doc-conda.txt  Staffan Ohlsson committed Apr 03, 2019 36   Matias Guijarro committed Feb 14, 2019 37 38 39 40  This installs mkdocs and all dependencies. In order to serve a local version of the documentation, start  Cyril Guilloud committed Feb 07, 2020 41 the mkdocs server with:  Staffan Ohlsson committed Apr 03, 2019 42 bash  Matias Guijarro committed Oct 08, 2019 43 44 cd /doc/ mkdocs serve  Staffan Ohlsson committed Apr 03, 2019 45 46  And visit http://localhost:8000  Matias Guijarro committed Feb 14, 2019 47 48   Laurent Claustre committed Feb 08, 2020 49 In order to update the documentation  Cyril Guilloud committed May 27, 2019 50 http://localhost:8000/dev_documentation.html  Staffan Ohlsson committed Apr 03, 2019 51 52 53 Please do the following bash  Matias Guijarro committed Oct 08, 2019 54 55 cd /doc/docs dev_documentation.md  Staffan Ohlsson committed Apr 03, 2019 56 57   Cyril Guilloud committed May 27, 2019 58 59 Once you save **dev_documentation.md** you can see the new version by reloading  Staffan Ohlsson committed Apr 03, 2019 60 http://localhost:8000/dev_documentation.html  Cyril Guilloud committed Nov 22, 2018 61 62 63 64 65  ## New controller documentation What to include in code / What to put in mkdoc ???  Laurent Claustre committed Feb 08, 2020 66 67 Create a new file, for instance config_mynewcontroller.md  Cyril Guilloud committed Mar 10, 2020 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 committed Nov 22, 2018 70   Staffan Ohlsson committed Apr 03, 2019 71 ### Example:  Matias Guijarro committed Feb 14, 2019 72   Staffan Ohlsson committed Apr 03, 2019 73 **ESRF - PePU controller**  Matias Guijarro committed Feb 14, 2019 74   Staffan Ohlsson committed Apr 03, 2019 75 Example YAML_ configuration:  Matias Guijarro committed Feb 14, 2019 76   Staffan Ohlsson committed Apr 03, 2019 77 yaml  Matias Guijarro committed Feb 14, 2019 78   Staffan Ohlsson committed Apr 03, 2019 79 80 81 82 83 84 85 86  plugin: bliss class: PEPU module: pepu name: pepudcm2 tcp: url: pepudcm2 template: renishaw # optional   Matias Guijarro committed Feb 14, 2019 87   Staffan Ohlsson committed Apr 03, 2019 88 Usage:  Cyril Guilloud committed Nov 22, 2018 89   Staffan Ohlsson committed Apr 03, 2019 90 91 92  >>> from bliss.config.static import get_config >>> from bliss.controllers.pepu import Stream, Trigger, Signal, ChannelMode  Cyril Guilloud committed Nov 22, 2018 93   Staffan Ohlsson committed Apr 03, 2019 94 >>> config = get_config()  Matias Guijarro committed Feb 14, 2019 95   Staffan Ohlsson committed Apr 03, 2019 96 97 >>> pepudcm2 = config.get('pepudcm2')   Cyril Guilloud committed Nov 22, 2018 98   Staffan Ohlsson committed Apr 03, 2019 99 100 For the counter interface, see the PePU scan support documentation   Cyril Guilloud committed Nov 22, 2018 101 102   Cyril Guilloud committed Feb 12, 2020 103 ### template:  Cyril Guilloud committed Nov 22, 2018 104   Matias Guijarro committed Feb 14, 2019 105   Staffan Ohlsson committed Apr 03, 2019 106 **ESRF - XXX controller**  Matias Guijarro committed Feb 14, 2019 107   Staffan Ohlsson committed Apr 03, 2019 108 Example YAML configuration:  Matias Guijarro committed Feb 14, 2019 109   Staffan Ohlsson committed Apr 03, 2019 110 yaml  Matias Guijarro committed Feb 14, 2019 111   Staffan Ohlsson committed Apr 03, 2019 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.  Matias Guijarro committed Feb 14, 2019 124   Cyril Guilloud committed Feb 12, 2020 125 126 127 ## Doc-strings  Cyril Guilloud committed Nov 22, 2018 128   Cyril Guilloud committed Nov 26, 2019 129 130 131 132 133 134 135 136 137 ## GUI doc examples: * Menu: Help ▶ IPython. * some symbols: 🗹 ✅ ❌ ❓ 🔴 🔶 □ 🗹 𝚫t µ → ⟶ 🡆 ← ↑ → ↓  Cyril Guilloud committed Nov 22, 2018 138 139 140 ## Markdown examples This page can be used as example of typical markdown usage.  Cyril Guilloud committed Nov 16, 2018 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 committed Nov 22, 2018 147 ### Documentation creation  Cyril Guilloud committed Nov 16, 2018 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  Benoit Formet committed Nov 03, 2020 153 154  * pymdown-extensions / markdown-inline-graphviz / Markdown * These packages are in requirements-doc-conda.txt  Cyril Guilloud committed Nov 16, 2018 155   Cyril Guilloud committed Jun 18, 2019 156 !!! note "At ESRF"  Staffan Ohlsson committed Apr 08, 2019 157 158  At ESRF, enter the BLISS development conda environment to install documentation requirements: bash  Matias Guijarro committed Oct 08, 2019 159  . blissenv -d  Staffan Ohlsson committed Apr 08, 2019 160    Cyril Guilloud committed Nov 16, 2018 161   Staffan Ohlsson committed Apr 03, 2019 162 bash  Matias Guijarro committed Oct 08, 2019 163 164 cd conda install --file requirements-doc-conda.txt  Staffan Ohlsson committed Apr 03, 2019 165 166 167  * launch mkdocs in server mode in your conda environment:  Cyril Guilloud committed Nov 16, 2018 168   Staffan Ohlsson committed Apr 03, 2019 169 bash  Matias Guijarro committed Oct 08, 2019 170 hostname  Staffan Ohlsson committed Apr 03, 2019 171 myhost  Matias Guijarro committed Oct 08, 2019 172 cd /doc/  Cyril Guilloud committed Feb 07, 2020 173 mkdocs serve -a 0.0.0.0:8888  Staffan Ohlsson committed Apr 03, 2019 174   Cyril Guilloud committed Nov 16, 2018 175   Staffan Ohlsson committed Apr 03, 2019 176 * and visit [http://myhost:8888](http://myhost:888) to see the documentation  Cyril Guilloud committed Nov 16, 2018 177 178 179 180 181  ### Level 3 title There are 6 levels of titles.  Cyril Guilloud committed Jun 18, 2019 182 !!! note "Title of the note"  Cyril Guilloud committed Nov 16, 2018 183 184 185 186  Titles of levels 2 to 6 are referenced in lateral right bar. #### Level 4 title  Cyril Guilloud committed Jun 18, 2019 187 !!! note "Title of the note"  Linus Pithan committed Mar 19, 2019 188 189  A note is made with an empty line, 3 !!!, note keyword and indented text.   Cyril Guilloud committed Nov 16, 2018 190   Cyril Guilloud committed Jun 18, 2019 191  !!! note "Title of the note"  Linus Pithan committed Mar 19, 2019 192 193  A note of made with an empty line and 3 !!!   Cyril Guilloud committed May 27, 2019 194 195   Cyril Guilloud committed Nov 16, 2018 196 197 198 199 ##### Level 5 title ###### Level 6 title  Cyril Guilloud committed Apr 19, 2021 200 201 202 203 204 205 206 207  ### 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.  Cyril Guilloud committed May 27, 2019 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 committed Nov 22, 2018 284 285 ### Lists  Cyril Guilloud committed Feb 12, 2020 286 287 #### bullet-list To create a bullet-list, an empty line must be respected:  Cyril Guilloud committed Nov 16, 2018 288 289 290  * and start 1st level lines with *  (star + space) * etc.  Cyril Guilloud committed Feb 12, 2020 291 292  - Nested list are possible, - with 4 spaces to begin the 2nd level lines.  Cyril Guilloud committed Nov 16, 2018 293 294 295  * and 8 for 3rd level * etc.  Cyril Guilloud committed Feb 12, 2020 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 committed Nov 16, 2018 312   Cyril Guilloud committed Mar 19, 2019 313 314 ### Links and references use:  Staffan Ohlsson committed Apr 03, 2019 315   Cyril Guilloud committed Mar 19, 2019 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)   Staffan Ohlsson committed Apr 03, 2019 321   Cyril Guilloud committed Mar 19, 2019 322 to produce:  Cyril Guilloud committed Nov 16, 2018 323 324  * mkdocs inner links: [Beamviewer Configuration](config_beamviewer.md).  Cyril Guilloud committed Feb 07, 2020 325 * mkdocs inner links with section ref: [code formatting](dev_guidelines.md#code-formatting)  Cyril Guilloud committed Nov 16, 2018 326 327 * outer links: [ESRF Gitlab](https://gitlab.esrf.fr/bliss/bliss)  Cyril Guilloud committed Mar 19, 2019 328   Cyril Guilloud committed Nov 22, 2018 329 ### Raw text  Cyril Guilloud committed Nov 16, 2018 330   Cyril Guilloud committed Feb 12, 2020 331 Inline raw text is surronded by single backquotes:  Cyril Guilloud committed Nov 16, 2018 332 333  raw text in monospace font  Matias Guijarro committed Feb 14, 2019 334   Cyril Guilloud committed Nov 16, 2018 335 336 result: raw text in monospace font  Cyril Guilloud committed Feb 12, 2020 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.   Cyril Guilloud committed May 27, 2019 342 343 344  In case you want to have a line break just insert two *spaces* at the end of the line, like this:  Staffan Ohlsson committed Apr 03, 2019 345   Cyril Guilloud committed Feb 12, 2020 346 347 348 349 350 351 line1 line2 line3 A bash command line is surronded by triple backquotes \ followed by bash:  Staffan Ohlsson committed Apr 03, 2019 352 353 markdown bash  Cyril Guilloud committed Feb 12, 2020 354   Cyril Guilloud committed May 27, 2019 355    Staffan Ohlsson committed Apr 03, 2019 356 357 358  Here is an example with <,> and [ in the text  Cyril Guilloud committed Nov 16, 2018 359   Staffan Ohlsson committed Apr 03, 2019 360 361 362 363 364 365 366 367 bash % bliss -h Usage: bliss [-l | --log-level=] [-s | --session=] bliss [-v | --version] bliss [-c | --create=] bliss [-d | --delete=] bliss [-h | --help]   Cyril Guilloud committed Nov 16, 2018 368 369   Cyril Guilloud committed Nov 22, 2018 370 371 372 ### Formated text #### Inline  Cyril Guilloud committed Nov 16, 2018 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 committed Nov 22, 2018 379 380 #### Python code  Staffan Ohlsson committed Apr 03, 2019 381 To specify a programing language, 3 backquotes can be used:  Cyril Guilloud committed Feb 12, 2020 382 383 384 385 386  python    Cyril Guilloud committed Nov 16, 2018 387   Cyril Guilloud committed Feb 12, 2020 388 Example:  Cyril Guilloud committed Nov 16, 2018 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 })], [], [], [])   Matias Guijarro committed Feb 14, 2019 398 399 !!! info With such formatting, Python code is easier to copy/paste in a shell.  Cyril Guilloud committed Nov 16, 2018 400   Cyril Guilloud committed Nov 22, 2018 401 #### YAML code  Cyril Guilloud committed Nov 16, 2018 402   Cyril Guilloud committed Feb 12, 2020 403 yaml  Cyril Guilloud committed Nov 16, 2018 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 committed Nov 22, 2018 413 414 #### Mathematic formula  Cyril Guilloud committed Nov 16, 2018 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 committed Nov 22, 2018 430 431 432 ### images and drawings #### SVG  Cyril Guilloud committed Nov 16, 2018 433 434 435  Code to include an existing svg file:  Linus Pithan committed Dec 12, 2019 436  ![Screenshot](img/ebv.svg)  Cyril Guilloud committed Nov 16, 2018 437 438  result:  Linus Pithan committed Dec 12, 2019 439 ![Screenshot](img/ebv.svg)  Cyril Guilloud committed Nov 16, 2018 440   Cyril Guilloud committed Nov 22, 2018 441 !!! note  Staffan Ohlsson committed Apr 08, 2019 442  To avoid fonts problems with svg files, texts can be converted to  Cyril Guilloud committed Nov 22, 2018 443  pathes. Select all and use Shift-Ctrl-C in Inkscape for example.  Cyril Guilloud committed Nov 16, 2018 444   Cyril Guilloud committed Nov 22, 2018 445 #### Bitmap  Cyril Guilloud committed Nov 16, 2018 446 447 448 449  PNG, SVG or GIF files can be used ![Screenshot](img/CT2/p201.png)  Cyril Guilloud committed May 11, 2021 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 `