Commit 017b1f05 authored by Cyril Guilloud's avatar Cyril Guilloud Committed by Matias Guijarro

+numbered lists +fix doc

parent fe4ac49f
Pipeline #21179 passed with stages
in 5 minutes and 13 seconds
......@@ -3,18 +3,18 @@
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
- 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
- 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](dev_write_motctrl.md) and only the specific part
will be kept in source code.
* embeded in source code
* inline comments to understand source code
* *docstring* after all user functions to be accessible from BLISS
- inline comments to understand source code
- *doc-string* after all user functions to be accessible from BLISS
shell with `help(<function>)`
## Installing documentation requirements
......@@ -100,7 +100,7 @@ For the counter interface, see the
`PePU scan support documentation <bliss.scanning.acquisition.pepu.html>`
###template:
### template:
**ESRF - XXX controller**
......@@ -122,6 +122,9 @@ Usage:
For more information, see the XXX documentation: XXX.
## Doc-strings
## GUI doc
......@@ -273,15 +276,32 @@ https://squidfunk.github.io/mkdocs-material/extensions/admonition/
### Lists
To create a list, an empty line must be respected:
#### bullet-list
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.
- Nested list are possible,
- with 4 spaces to begin the 2nd level lines.
* and 8 for 3rd level
* etc.
!!! 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.
### Links and references
use:
......@@ -301,32 +321,30 @@ to produce:
### Raw text
Inline raw text is placed between 2 backquotes:
Inline raw text is surronded by single backquotes:
`raw text in monospace font`
result: `raw text in monospace font`
A raw text block is defined using 4 spaces to begin a line and
respecting an empty line before block.
My text without any change,
but it has to be text without symbols.
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 defined with 3 \` (backquotes) followed by **bash**<br>
It looks like
line1
line2
line3
A bash command line is surronded by triple backquotes \` followed by `bash`:
```markdown
```bash
```
and you finish your script with 3 \` (backquotes) like
```markdown
<code>
```
```
......@@ -354,7 +372,13 @@ There are many formating marker to write text in *italic* or `raw text
#### Python code
To specify a programing language, 3 backquotes can be used:
```
```python
<code>
```
```
Example:
```python
from bliss.common.axis import Axis
from bliss.controllers.motors import icepap
......@@ -369,7 +393,7 @@ iceid2322 = icepap.Icepap("iceid2322", {"host": "iceid2322"},
#### YAML code
```YAML
```yaml
- controller:
class: icepap
host: iceid2322
......
......@@ -2,7 +2,7 @@ var anchors = Array.from(document.getElementsByClassName("md-nav__link"));
anchors.forEach(function(anchor) {
var sep = anchor.innerText.indexOf("|");
if (sep != -1) {
anchor.href = anchor.innerText.substring(sep + 1, anchor.innerText.length);
anchor.href = document.location.origin + "/" + anchor.innerText.substring(sep + 1, anchor.innerText.length);
anchor.innerText = anchor.innerText.substring(0,sep);
}
if (anchor.innerText.indexOf("\uD83D\uDDD7") != -1) { // &#x1F5D7; = "new window" char, see http://www.fileformat.info/info/unicode/char/1f5d7/index.htm
......
......@@ -138,7 +138,7 @@ nav:
- Data structure & access: data_structure.md
- "External saving": data_external_saving.md
- Developers corner:
- 'API documentation': api/index.html
- 'API documentation ⚙|api/index.html': api.md
- Guidelines: dev_guidelines.md
- Writing documentation: dev_documentation.md
- Communication API: dev_comm.md
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment