SCRUG-NA/2025
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[installation] Change to nightly

Browse Source
This commit is contained in:
Dirk Rössler
2025-10-30 12:04:59 +01:00
parent 2ff097f9d1
commit a31bc45cce
1441 changed files with 60368 additions and 56360 deletions
Download Patch File Download Diff File Expand all files Collapse all files

230
share/doc/seiscomp/html/_sources/base/style-guide.rst.txt
View File

@ -8,19 +8,23 @@ Style Guide for Documentation
File Layout
===========
The documentation of an executable module comes as a pair of source files:
The documentation of an executable module or plugin comes as a pair of source
files:
* A description XML file (.xml) giving command details, command-line and configuration parameters,
* A documentation reST text file (.rst) gives a more-detailed module description and examples.
* A :ref:`description XML file (.xml) <contributing_documentation_XML>` giving
command details, command-line and configuration parameters,
* A :ref:`documentation reST text file (.rst) <documentation_style_guide_rst>`
gives a more-detailed module description and examples.
Any other documentation, e.g. this style guide, tutorials, etc. only require the
documentation reST text file.
The reST text file should follow the guidelines in this style guide.
The :ref:`contributing_documentation` section details the documentation
requirements for executables including the structure of description XML files.
The :ref:`contributing_documentation` section details
the documentation requirements for executables including the structure of description XML files.
.. _documentation_style_guide_rst:
Documentation Syntax
====================
@ -35,10 +39,10 @@ Add information about testing and examples into their own sections.
General principles
------------------
- If possible, keep line lengths under 80 characters.
- It eases later editing if sentences in the raw RST start on a new
* If possible, confine lines to 80 characters.
* It eases later editing if sentences in the raw RST start on a new
line, even though they will flow together in the finished document.
- It is helpful if long text objects such as HTML link text each
* It is helpful if long text objects such as HTML link text each
appear on their own line.
@ -53,14 +57,14 @@ description information in the appropriate part of the documentation.
While RST doesn't care too much about what syntax is used for
headings, it is best to stick to one style consistently.
Thus, you will generally need only two levels of headings but you can add more.
Thus, you will generally need only few levels of headings but you can add more.
+-------+------------------------------+
| Level | Mark up beneath heading text |
+=======+==============================+
| 1 | ' ==== ' |
+-------+------------------------------+
| 2 | " ---- " |
| 2 | ' - - - ' |
+-------+------------------------------+
| 3 | ' ~~~~ ' |
+-------+------------------------------+
@ -89,8 +93,9 @@ Parts such as Examples are marked in **bold**.
However notes and figures should use the appropriate RST directive, and don't require their own headings.
- One blank line below headings is enough.
- Two lines above are often used, and this looks better than one.
* One blank line below headings is enough.
* Two lines above are often used, and this looks better than one.
Lists
-----
@ -122,10 +127,44 @@ Use numbered or unnumbered lists at several levels.
* subitem 2.
Other markup tools and conventions
----------------------------------
Tables
------
- **Code fragments:** Use the reST code-block syntax for code fragments, with
Tables may be generated as CSV tables defining the
* column width
* header text
* alignment
* delimiter
* table content
.. code-block:: rst
.. csv-table::
:widths: 20 80
:header: Item, Value
:align: center
:delim: ;
1; value for item 1
2; value for item 2
**Result:**
.. csv-table::
:widths: 20 80
:header: Item, Value
:align: center
:delim: ;
1; value for item 1
2; value for item 2
Other tools and conventions
---------------------------
* **Code fragments:** Use the reST code-block syntax for code fragments, with
flavors like "c", "python", "sh", "bash", "properties´" or "xml" as appropriate:
.. code-block:: rst
@ -142,7 +181,7 @@ Other markup tools and conventions
#!/bin/bash
echo $SEISCOMP_ROOT
- **Configuration parameters:** Configuration values have a special
* **Configuration parameters:** Configuration values have a special
syntax. Use the ':confval:' indicator for referencing a module configuration
parameter:
@ -150,20 +189,24 @@ Other markup tools and conventions
:confval:`logging.level`
Result: :confval:`logging.level`.
Using this tag allows a link to be made within the documentation of that module
to the given configuration of the same module. The parameter must be defined
in the description XML file of the module.
- **Command-line options:** Command-line options have a special
* **Command-line options:** Command-line options have a special
syntax. Use the ':option:' indicator for referencing an option:
.. code-block:: rst
:option:`--help`
The option must be defined in the description XML file of the module.
Result: :option:`--help`.
- **Configuration files:** Use the reST ':file:' indicator to refer to files such
The option must be defined in the description XML file of the module or global.
* **Configuration files:** Use the reST ':file:' indicator to refer to files such
as configuration files:
.. code-block:: rst
@ -172,7 +215,7 @@ Other markup tools and conventions
Result: :file:`$SEISCOMP_ROOT/etc/scautopick.cfg`
- **Programs:** Use the reST ':program:' indicator for |scname| programs:
* **Programs:** Use the reST ':program:' indicator for |scname| programs:
.. code-block:: rst
@ -180,7 +223,7 @@ Other markup tools and conventions
Result: :program:`scautopick`
- **References:** Use the reST ':ref:' indicator for cross referencing |scname|
* **References:** Use the reST ':ref:' indicator for cross referencing |scname|
module documentation pages:
.. code-block:: rst
@ -189,7 +232,7 @@ Other markup tools and conventions
Result: :ref:`scautopick`
- **Glossary:** Use the reST ':term:' indicator for referencing terms in the
* **Glossary:** Use the reST ':term:' indicator for referencing terms in the
|scname| :ref:`glossary`:
.. code-block:: rst
@ -198,6 +241,27 @@ Other markup tools and conventions
Result: :term:`magnitude`
* **Download link:** Use the reST ':download:' indicator for referencing a file
in the local file system. The file is loaded when clicking on the link
.. code-block:: rst
:download:`changelog <./CHANGELOG.md>`
Result: :download:`changelog <./CHANGELOG.md>`
.. hint::
When using the reST indicators, text may be given which is shown instead of
the actual link. Enclose the actual link within '<link>' and prepend the
actual text. Example
.. code-block:: rst
:ref:`the scautopick module <scautopick>`
Result: :ref:`the scautopick module <scautopick>`
.. _documentation_style_guide_links:
@ -208,19 +272,19 @@ Create links to sections and subsections within and to figures the text which c
Use unique link names, e.g. including the upper-level section name or the module name.
Use appropriate short names to fit within the texts.
Link within this documentation to the section on headings:
Create a label within this |scname| documentation to the section on headings:
.. code-block:: rst
.. _documentation_style_guide_headings:
Reference:
and refer to the lable within the text:
.. code-block:: rst
:ref:`short name <documentation_style_guide_headings>`
:ref:`link to this section <documentation_style_guide_headings>`
Result: :ref:`short name <documentation_style_guide_headings>`
Result: :ref:`link to this section <documentation_style_guide_headings>`
External links and references
@ -336,66 +400,19 @@ Make sensible use of it!
This adds an important warning.
English Language
================
- SeisComP (capital P), not SeisComP 3 or SC3.
- |scname| module names are proper nouns, even though written with lower case.
Thus they do not need an article.
* Correct: "Although :program:`scmaster` receives a message"
* Incorrect: "Although the scmaster receives a message..."
A sentence may begin with a lower case module name e.g. "scmaster has five modes..."
avoiding this: "The :program:`scmaster` module has..."
- Word separation:
- Separate words:
base class, wave number, time span
- One word:
aftershock, foreshock, *and mainshock too*,
bandpass, eigenperiod etc., metadata, standalone, username, workflow, waveform
- Difficult:
high-pass filter; command line; command-line parameter
- Hyphenation for compound adjectives: yes, before a noun; after verb to be is harder.
See the `discussion`_, e.g.:
- Use command-line parameters
- Type on the command line
- Spelling:
Use American English:
- With 'z': digitizer, realize, visualize, synchronize, behavior, color.
- With 's': license.
- Center, data center.
- Case:
- SEED, miniSEED (miniSEED in :cite:t:`libmseed-github`, or MiniSEED,
but Mini-SEED appears in Appendix G of the :cite:t:`seed-2012`.)
- Ctrl+S for 'control' key plus 's'.
- MySQL, PostgreSQL, MariaDB
- Abbreviations:
- e.g., i.e.
- STA, LTA, STA/LTA detector
- TAR file
.. _documentation_style_guide_images:
Adding Images
=============
Images
------
Code implementation
-------------------
~~~~~~~~~~~~~~~~~~~
The images will be moved to the correct location during the documentation build.
* Place image files in a suitable sub-directory of :file:`descriptions/media`.
* Add images with fixed width.
* Define image alignment.
* Add image captions.
* Store images in a separate directory of below the directory where the
documentation is kept.
@ -436,7 +453,7 @@ Compare with the :ref:`concept section on configuration<concepts_configuration-c
Image style and format
----------------------
~~~~~~~~~~~~~~~~~~~~~~
* Images shall be informative.
* Images must not have any offensive or inappropriate content.
@ -451,6 +468,57 @@ Image style and format
X-forwarding may distort the application features.
English Language
================
* SeisComP (capital P), not SeisComP 3 or SC3.
* |scname| module names are proper nouns, even though written with lower case.
Thus they do not need an article.
* Correct: "Although :program:`scmaster` receives a message"
* Incorrect: "Although the scmaster receives a message..."
A sentence may begin with a lower case module name e.g. "scmaster has five modes..."
avoiding this: "The :program:`scmaster` module has..."
* Word separation:
* Separate words:
base class, wave number, time span
* One word:
aftershock, foreshock, *and mainshock too*,
bandpass, eigenperiod etc., metadata, standalone, username, workflow, waveform
* Difficult:
high-pass filter; command line; command-line parameter
* Hyphenation for compound adjectives: yes, before a noun; after verb to be is harder.
See the `discussion`_, e.g.:
* Use command-line parameters
* Type on the command line
* Spelling:
Use American English:
* With 'z': digitizer, realize, visualize, synchronize, behavior, color.
* With 's': license.
* Center, data center.
* Case:
* SEED, miniSEED (miniSEED in :cite:t:`libmseed-github`, or MiniSEED,
but Mini-SEED appears in Appendix G of the :cite:t:`seed-2012`.)
* Ctrl+S for 'control' key plus 's'.
* MySQL, PostgreSQL, MariaDB
* Abbreviations:
* e.g., i.e.
* STA, LTA, STA/LTA detector
* TAR file
References
==========