[installation] Change to nightly
This commit is contained in:
@ -10,18 +10,17 @@ It aims to document the configuration and command line options for
|
||||
consistent way. The functionality of |scname| differs between
|
||||
versions so the documentation is versioned along with |scname|.
|
||||
For more general topics and tutorials please refer to the
|
||||
`SeisComP wiki`_.
|
||||
|scname| website and documentation :cite:p:`seiscomp`.
|
||||
|
||||
The documentation is written in `reStructuredText`_ (reST) a
|
||||
simple text mark up format. The documentation is generated using `Sphinx`_
|
||||
which is used to create the `Python documentation`_.
|
||||
The Sphinx website has a very good
|
||||
`introduction to reST`_ and also covers the Sphinx specific
|
||||
`directives`_.
|
||||
The documentation is written in :cite:t:`reStructuredText` (reST) a simple text
|
||||
mark up format. The documentation is generated using Sphinx :cite:p:`sphinx`
|
||||
which is used to create the Python documentation :cite:p:`python-doc`.
|
||||
The Sphinx website :cite:p:`reStructuredText-sphinx` has a very good
|
||||
introduction to reST and also covers the Sphinx-specific
|
||||
directives :cite:p:`reStructuredText-directives`.
|
||||
|
||||
If you would like to add to this documentation or you find an error, then please
|
||||
submit a patch to `SeisComP on GitHub`_ or report to the
|
||||
SeisComP `discussion forum`_.
|
||||
submit a patch to :cite:t:`seiscomp-github` or report to the :cite:t:`seiscomp-forum`.
|
||||
|
||||
.. note::
|
||||
|
||||
@ -33,54 +32,64 @@ then you can use the *Show Source* link on each page to view the reST
|
||||
source. The source and the documentation files for executables (see below) are
|
||||
good starting points for a new patch.
|
||||
|
||||
|
||||
Documenting Executables
|
||||
=======================
|
||||
|
||||
The documentation for executables is generated from two sources:
|
||||
The documentation for modules and plugins is generated from two sources:
|
||||
|
||||
'executable'.xml
|
||||
An XML file that contains a brief description of the command,
|
||||
markup describing the command line parameters, and any
|
||||
configuration parameters for the executable. Each parameter should
|
||||
An :ref:`XML file <contributing_documentation_XML>` that contains a brief
|
||||
description of the command, markup describing the command line parameters,
|
||||
and any configuration parameters for the executable. Each parameter should
|
||||
have a brief description of the purpose of the parameter.
|
||||
|
||||
The description should be plain text and not contain reST markup. Where parameters are common across
|
||||
a number of executables they should be placed in the appropriate common file and referred to using
|
||||
their publicID.
|
||||
The description should be plain text and not contain reST markup. Where
|
||||
parameters are common across a number of executables they should be placed
|
||||
in the appropriate common file and referred to using their publicID.
|
||||
|
||||
All XML files live in the :file:`doc/apps` directory of the source
|
||||
distribution or in :file:`etc/descriptions` of an installation.
|
||||
|
||||
'executable'.rst
|
||||
This is a text file in reST markup that gives any more-detailed description and examples for the executable.
|
||||
It is combined with the corresponding .xml to create the full documentation.
|
||||
This is a RST text file in :ref:`reST markup <reStructuredText>` that gives
|
||||
any more-detailed description and examples for modules or plugins. It is
|
||||
combined with the corresponding :file:`executable.xml` file to create the
|
||||
full HTML documentation and man pages of a module or plugin.
|
||||
|
||||
When listed in a table of content, the RST file allows generating general
|
||||
content without providing an XML file. Examples can be found in the
|
||||
`documentation index file`_ .
|
||||
|
||||
The first entry in the file should be a paragraph giving a more
|
||||
detailed description of the executable.
|
||||
detailed description of the executable. The following paragraphs provide
|
||||
background information, use cases and examples.
|
||||
|
||||
These two files should be placed in a :file:`descriptions` sub-directory of the
|
||||
respective module, e.g. :file:`src/seedlink/apps/seedlink/descriptions/seedlink.rst`.
|
||||
The intention is that the documentation is close to the code to make it easier for developers to keep the
|
||||
documentation up to date with code changes.
|
||||
respective module or plugin, e.g., the `scolv description`_ .
|
||||
The intention is that the documentation is close to the code to make it easier
|
||||
for developers to keep the documentation up to date with code changes.
|
||||
|
||||
For a new executable an entry should also be made in the man section of :file:`conf.py`.
|
||||
The man page is a short form of the documentation that is generated from only the .xml file.
|
||||
For a new executable an entry can also be made in the man section of
|
||||
:file:`conf.py`. For |scname| modules located, `documentation templates directory`_.
|
||||
|
||||
The man page is a short form of the documentation of a module that is generated
|
||||
from the XML and the RST files.
|
||||
Example:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
man scolv
|
||||
|
||||
|
||||
Images
|
||||
======
|
||||
Creating the RST
|
||||
================
|
||||
|
||||
Any images should be placed in a suitable sub-directory of :file:`descriptions/media`.
|
||||
Read the :ref:`documentation on image styles <documentation_style_guide_image>` for more details.
|
||||
The images can then be referred to (in .rst) like::
|
||||
The RST file should be written according to the
|
||||
:ref:`documentation style guide <documentation_style_guide>`.
|
||||
|
||||
.. figure:: media/scolv/scolv-overview.png
|
||||
:width: 16cm
|
||||
:align: center
|
||||
|
||||
Overview of the defrobnicator switches in :ref:`scolv`.
|
||||
|
||||
The images will be moved to the correct location during the documentation build.
|
||||
|
||||
.. _contributing_documentation_XML:
|
||||
|
||||
Understanding the XML
|
||||
=====================
|
||||
@ -97,10 +106,13 @@ Any description XML uses the root element *seiscomp*:
|
||||
...
|
||||
</seiscomp>
|
||||
|
||||
Three elements are used inside the root element: :ref:`module<xml-module>`, :ref:`plugin<xml-plugin>` and :ref:`binding<xml-binding>`.
|
||||
Modules, plugins and bindings can be described in one XML or split up into one file per description. It is better to
|
||||
have things as close as possible. A module and its binding should go into one module.XML whereas plugins should
|
||||
go into separate XML files.
|
||||
Three elements are used inside the root element: :ref:`module<xml-module>`,
|
||||
:ref:`plugin<xml-plugin>` and :ref:`binding<xml-binding>`.
|
||||
Modules, plugins and bindings can be described in one XML or split up into one
|
||||
file per description. It is better to have things as close as possible. A module
|
||||
and its binding should go into one module.XML whereas plugins should go into
|
||||
separate XML files. Examples can be found in the source code as well as in the
|
||||
XML files installed in :file:`seiscomp/etc/descriptions`.
|
||||
|
||||
|
||||
.. _xml-module:
|
||||
@ -295,7 +307,6 @@ Element: **configuration**
|
||||
| | | | |
|
||||
+-------------------+----------+-----------+---------------------------------------------------+
|
||||
|
||||
|
||||
.. _xml-configuration-parameter:
|
||||
|
||||
Element: **parameter**
|
||||
@ -312,6 +323,13 @@ Element: **parameter**
|
||||
| | | | configurator to provide specialized input |
|
||||
| | | | widgets. It is also important for the user |
|
||||
| | | | how the parameter is read by the module. |
|
||||
| | | | Supported are: *uint, list:uint, int, list:uint, |
|
||||
| | | | double, list:double, float, list:float, file, |
|
||||
| | | | list:file, directory, list:directory, time |
|
||||
| | | | list:time, host-with-port, boolean, gradient* |
|
||||
+-------------------+----------+-----------+---------------------------------------------------+
|
||||
| **options** | attrib | no | Options to type if type is file or directory. |
|
||||
| | | | Supported: *read, write, execute* |
|
||||
+-------------------+----------+-----------+---------------------------------------------------+
|
||||
| **unit** | attrib | no | An optional unit such as "s" or "km" or |
|
||||
| | | | "deg". |
|
||||
@ -319,9 +337,28 @@ Element: **parameter**
|
||||
| **default** | attrib | no | The default value the module uses if this |
|
||||
| | | | parameter is not configured. |
|
||||
+-------------------+----------+-----------+---------------------------------------------------+
|
||||
| **values** | element | no | Lists the supported value separated by comma. For |
|
||||
| | attrib | | files, the list describes file name suffices. |
|
||||
+-------------------+----------+-----------+---------------------------------------------------+
|
||||
| **range** | element | no | The range of values. Format: minimum:maximum |
|
||||
| | attrib | | |
|
||||
+-------------------+----------+-----------+---------------------------------------------------+
|
||||
| **description** | element | no | Gives a brief description of the parameter. |
|
||||
+-------------------+----------+-----------+---------------------------------------------------+
|
||||
|
||||
.. note::
|
||||
|
||||
Further explanations of **type**:
|
||||
|
||||
* uint: Non-negative integer. Example values: 0, 1
|
||||
* gradient: Colon-separated pairs of value and color. Example:
|
||||
-4:"rgb(0,0,255)".
|
||||
* host-with-port: Colon-separated pairs of host address and port number.
|
||||
Example: localhost:8080.
|
||||
* time: Any :ref:`time format supported by SeisComP <time-formats>` is
|
||||
possible unless stated differently.
|
||||
* list: One ore more values separated by comma.
|
||||
|
||||
.. _xml-configuration-struct:
|
||||
|
||||
Element: **struct**
|
||||
@ -333,6 +370,8 @@ Element: **struct**
|
||||
| | | | used in a configurator to give a selection |
|
||||
| | | | of available types to be instantiated. |
|
||||
+-------------------+----------+-----------+---------------------------------------------------+
|
||||
| **title** | attrib | no | The title of the struct as shown, e.g. in scconfig|
|
||||
+-------------------+----------+-----------+---------------------------------------------------+
|
||||
| **link** | attrib | no | The absolute reference parameter as it would |
|
||||
| | | | appear in the configuration file which |
|
||||
| | | | holds all instantiated structures. |
|
||||
@ -362,8 +401,21 @@ Element: **struct**
|
||||
| **group** | element | no | Describes a group part of this struct. See |
|
||||
| | | | :ref:`group<xml-configuration-group>`. |
|
||||
+-------------------+----------+-----------+---------------------------------------------------+
|
||||
| **aliases** | attrib | no | Explains where to find alias parameters. |
|
||||
+-------------------+----------+-----------+---------------------------------------------------+
|
||||
|
||||
.. _xml-configuration-extend-struct:
|
||||
|
||||
Element: **extend-struct**
|
||||
|
||||
+-------------------+----------+-----------+---------------------------------------------------+
|
||||
| Name | XML type | Mandatory | Description |
|
||||
+===================+==========+===========+===================================================+
|
||||
| **type** | attrib | yes | The name of the struct type to be extended. This |
|
||||
+-------------------+----------+-----------+---------------------------------------------------+
|
||||
| **match-name** | attrib | no | The name given of the struct with parameters |
|
||||
| | | | extending name the struct given by name. |
|
||||
+-------------------+----------+-----------+---------------------------------------------------+
|
||||
|
||||
.. _xml-configuration-group:
|
||||
|
||||
@ -386,7 +438,6 @@ Element: **group**
|
||||
| **group** | element | no | Describes a group part of this group. |
|
||||
+-------------------+----------+-----------+---------------------------------------------------+
|
||||
|
||||
|
||||
Below is an example of the plugin definition for the NonLinLoc plugin. It contains
|
||||
groups, parameters and structures.
|
||||
|
||||
@ -406,7 +457,7 @@ groups, parameters and structures.
|
||||
</description>
|
||||
</parameter>
|
||||
|
||||
<parameter name="outputPath" type="path" default="/tmp/sc3.nll">
|
||||
<parameter name="outputPath" type="directory" default="/tmp/sc3.nll">
|
||||
<description>
|
||||
Defines the output path for all native NonLinLoc input and
|
||||
output files.
|
||||
@ -438,7 +489,6 @@ groups, parameters and structures.
|
||||
</seiscomp>
|
||||
|
||||
|
||||
|
||||
.. _xml-command-line:
|
||||
|
||||
Command-line
|
||||
@ -466,7 +516,6 @@ Element: **command-line**
|
||||
| | | | :ref:`group<xml-command-line-group>`. |
|
||||
+---------------------+----------+-----------+-----------------------------------------------+
|
||||
|
||||
|
||||
.. _xml-command-line-group:
|
||||
|
||||
Element: **group**
|
||||
@ -484,7 +533,6 @@ Element: **group**
|
||||
| | | | publicID. |
|
||||
+---------------------+----------+-----------+-----------------------------------------------+
|
||||
|
||||
|
||||
.. _xml-command-line-option:
|
||||
|
||||
Element: **option**
|
||||
@ -520,7 +568,6 @@ Element: **option**
|
||||
| **description** | element | no | Gives a brief description of the option. |
|
||||
+---------------------+----------+-----------+-----------------------------------------------+
|
||||
|
||||
|
||||
Below is an example of the module definition for :program:`scautoloc` (extract).
|
||||
|
||||
.. code-block:: xml
|
||||
@ -533,6 +580,9 @@ Below is an example of the module definition for :program:`scautoloc` (extract).
|
||||
...
|
||||
</configuration>
|
||||
<command-line>
|
||||
<synopsis>
|
||||
scautoloc [options]
|
||||
</synopsis>
|
||||
<group name="Generic">
|
||||
<optionReference>generic#help</optionReference>
|
||||
<optionReference>generic#version</optionReference>
|
||||
@ -571,11 +621,6 @@ References
|
||||
|
||||
.. target-notes::
|
||||
|
||||
.. _`SeisComP wiki` : https://www.seiscomp.de/
|
||||
.. _`reStructuredText` : https://docutils.sourceforge.io/rst.html
|
||||
.. _`Sphinx` : https://www.sphinx-doc.org/
|
||||
.. _`Python documentation` : https://docs.python.org/
|
||||
.. _`introduction to reST` : https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
|
||||
.. _`directives` : https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html
|
||||
.. _`SeisComP on GitHub` : https://github.com/SeisComP
|
||||
.. _`discussion forum` : https://forum.seiscomp.de
|
||||
.. _`documentation index file` : https://github.com/SeisComP/seiscomp/blob/master/doc/templates/index.rst
|
||||
.. _`scolv description` : https://github.com/SeisComP/main/blob/master/apps/gui-qt/scolv/descriptions/
|
||||
.. _`documentation templates directory` : https://github.com/SeisComP/seiscomp/tree/master/doc/templates
|
||||
|
||||
Reference in New Issue
Block a user