[installation] Change to nightly

2025-10-30 12:04:59 +01:00
parent 2ff097f9d1
commit a31bc45cce
1441 changed files with 60368 additions and 56360 deletions
--- a/share/doc/seiscomp/html/base/style-guide.html
+++ b/share/doc/seiscomp/html/base/style-guide.html
@ -4,7 +4,7 @@
  <head>
    <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

-    <title>Style Guide for Documentation &#8212; SeisComP Release documentation</title>
+    <title>Style Guide for Documentation &#8212; SeisComP Development documentation</title>
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="../_static/seiscomp.css" type="text/css" />
    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=72bcf2f2" />
@ -12,7 +12,7 @@
    <link rel="stylesheet" type="text/css" href="../_static/graphviz.css?v=eafc0fe6" />
    <script type="text/javascript" src="../_static/seiscomp.js"></script>
    <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
-    <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js?v=823bb831"></script>
+    <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js?v=744d344a"></script>
    <script src="../_static/doctools.js?v=888ff710"></script>
    <script src="../_static/sphinx_highlight.js?v=4825356b"></script>
    <link rel="index" title="Index" href="../genindex.html" />
@ -25,8 +25,8 @@
      <div class="container">
        <div class="brand">
          <img class="logo" src="../_static/brands/seiscomp/text/white.svg"/>
-           <!-- span class="title">SeisComP Release</span -->
-          <span class="version">6.9.0</span>
+           <!-- span class="title">SeisComP Development</span -->
+          <span class="version">7.0.0</span>
        </div>
      </div>
    </div>
@ -70,19 +70,22 @@
 <span id="documentation-style-guide"></span><h1>Style Guide for Documentation<a class="headerlink" href="#style-guide-for-documentation" title="Permalink to this heading">¶</a></h1>
 <section id="file-layout">
 <h2>File Layout<a class="headerlink" href="#file-layout" title="Permalink to this heading">¶</a></h2>
-<p>The documentation of an executable module comes as a pair of source files:</p>
+<p>The documentation of an executable module or plugin comes as a pair of source
+files:</p>
 <ul class="simple">
-<li><p>A description XML file (.xml) giving command details, command-line and configuration parameters,</p></li>
-<li><p>A documentation reST text file (.rst) gives a more-detailed module description and examples.</p></li>
+<li><p>A <a class="reference internal" href="contributing-docs.html#contributing-documentation-xml"><span class="std std-ref">description XML file (.xml)</span></a> giving
+command details, command-line and configuration parameters,</p></li>
+<li><p>A <a class="reference internal" href="#documentation-style-guide-rst"><span class="std std-ref">documentation reST text file (.rst)</span></a>
+gives a more-detailed module description and examples.</p></li>
 </ul>
 <p>Any other documentation, e.g. this style guide, tutorials, etc. only require the
 documentation reST text file.</p>
-<p>The reST text file should follow the guidelines in this style guide.</p>
-<p>The <a class="reference internal" href="contributing-docs.html#contributing-documentation"><span class="std std-ref">Contributing Documentation</span></a> section details
-the documentation requirements for executables including the structure of description XML files.</p>
+<p>The reST text file should follow the guidelines in this style guide.
+The <a class="reference internal" href="contributing-docs.html#contributing-documentation"><span class="std std-ref">Contributing Documentation</span></a> section details the documentation
+requirements for executables including the structure of description XML files.</p>
 </section>
 <section id="documentation-syntax">
-<h2>Documentation Syntax<a class="headerlink" href="#documentation-syntax" title="Permalink to this heading">¶</a></h2>
+<span id="documentation-style-guide-rst"></span><h2>Documentation Syntax<a class="headerlink" href="#documentation-syntax" title="Permalink to this heading">¶</a></h2>
 <p>A template for a typical application or module in reST is in <code class="file docutils literal notranslate"><span class="pre">doc/templates/app.rst</span></code>.
 An introductory paragraph should describe the purpose of the executable.
 The introduction is followed be any additional information needed to understand
@ -91,7 +94,7 @@ Add information about testing and examples into their own sections.</p>
 <section id="general-principles">
 <h3>General principles<a class="headerlink" href="#general-principles" title="Permalink to this heading">¶</a></h3>
 <ul class="simple">
-<li><p>If possible, keep line lengths under 80 characters.</p></li>
+<li><p>If possible, confine lines to 80 characters.</p></li>
 <li><p>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.</p></li>
 <li><p>It is helpful if long text objects such as HTML link text each
@ -106,7 +109,7 @@ build script will take this text and assemble it with other
 description information in the appropriate part of the documentation.</p>
 <p>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.</p>
+Thus, you will generally need only few levels of headings but you can add more.</p>
 <table class="docutils align-default">
 <thead>
 <tr class="row-odd"><th class="head"><p>Level</p></th>
@ -118,7 +121,7 @@ Thus, you will generally need only two levels of headings but you can add more.<
 <td><p>‘ ==== ‘</p></td>
 </tr>
 <tr class="row-odd"><td><p>2</p></td>
-<td><p>“ —- “</p></td>
+<td><p>‘ - - - ‘</p></td>
 </tr>
 <tr class="row-even"><td><p>3</p></td>
 <td><p>‘ ~~~~ ‘</p></td>
@ -181,8 +184,49 @@ Some<span class="w"> </span>text
 </li>
 </ol>
 </section>
-<section id="other-markup-tools-and-conventions">
-<h3>Other markup tools and conventions<a class="headerlink" href="#other-markup-tools-and-conventions" title="Permalink to this heading">¶</a></h3>
+<section id="tables">
+<h3>Tables<a class="headerlink" href="#tables" title="Permalink to this heading">¶</a></h3>
+<p>Tables may be generated as CSV tables defining the</p>
+<ul class="simple">
+<li><p>column width</p></li>
+<li><p>header text</p></li>
+<li><p>alignment</p></li>
+<li><p>delimiter</p></li>
+<li><p>table content</p></li>
+</ul>
+<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">csv-table</span><span class="p">::</span>
+   <span class="nc">:widths:</span> 20 80
+   <span class="nc">:header:</span> Item, Value
+   <span class="nc">:align:</span> center
+   <span class="nc">:delim:</span> ;
+
+   1; value for item 1
+   2; value for item 2
+</pre></div>
+</div>
+<p><strong>Result:</strong></p>
+<table class="docutils align-center">
+<colgroup>
+<col style="width: 20.0%" />
+<col style="width: 80.0%" />
+</colgroup>
+<thead>
+<tr class="row-odd"><th class="head"><p>Item</p></th>
+<th class="head"><p>Value</p></th>
+</tr>
+</thead>
+<tbody>
+<tr class="row-even"><td><p>1</p></td>
+<td><p>value for item 1</p></td>
+</tr>
+<tr class="row-odd"><td><p>2</p></td>
+<td><p>value for item 2</p></td>
+</tr>
+</tbody>
+</table>
+</section>
+<section id="other-tools-and-conventions">
+<h3>Other tools and conventions<a class="headerlink" href="#other-tools-and-conventions" title="Permalink to this heading">¶</a></h3>
 <ul>
 <li><p><strong>Code fragments:</strong> Use the reST code-block syntax for code fragments, with
 flavors like “c”, “python”, “sh”, “bash”, “properties´” or “xml” as appropriate:</p>
@ -204,6 +248,7 @@ parameter:</p>
 <div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="na">:confval:</span><span class="nv">`logging.level`</span>
 </pre></div>
 </div>
+<p>Result: <a class="reference internal" href="../apps/global.html#confval-logging.level"><code class="xref std std-confval docutils literal notranslate"><span class="pre">logging.level</span></code></a>.</p>
 <p>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.</p>
@ -213,7 +258,8 @@ syntax. Use the ‘:option:’ indicator for referencing an option:</p>
 <div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="na">:option:</span><span class="nv">`--help`</span>
 </pre></div>
 </div>
-<p>The option must be defined in the description XML file of the module.</p>
+<p>Result: <code class="xref std std-option docutils literal notranslate"><span class="pre">--help</span></code>.</p>
+<p>The option must be defined in the description XML file of the module or global.</p>
 </li>
 <li><p><strong>Configuration files:</strong> Use the reST ‘:file:’ indicator to refer to files such
 as configuration files:</p>
@ -242,22 +288,39 @@ module documentation pages:</p>
 </div>
 <p>Result: <a class="reference internal" href="glossary.html#term-magnitude"><span class="xref std std-term">magnitude</span></a></p>
 </li>
+<li><p><strong>Download link:</strong> Use the reST ‘:download:’ indicator for referencing a file
+in the local file system. The file is loaded when clicking on the link</p>
+<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="na">:download:</span><span class="nv">`changelog &lt;./CHANGELOG.md&gt;`</span>
+</pre></div>
+</div>
+<p>Result: <a class="reference download internal" download="" href="../_downloads/53c856d6b046c257085795877bbb748e/CHANGELOG.md"><code class="xref download docutils literal notranslate"><span class="pre">changelog</span></code></a></p>
+</li>
 </ul>
+<div class="admonition hint">
+<p class="admonition-title">Hint</p>
+<p>When using the reST indicators, text may be given which is shown instead of
+the actual link. Enclose the actual link within ‘&lt;link&gt;’ and prepend the
+actual text. Example</p>
+<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="na">:ref:</span><span class="nv">`the scautopick module &lt;scautopick&gt;`</span>
+</pre></div>
+</div>
+<p>Result: <a class="reference internal" href="../apps/scautopick.html#scautopick"><span class="std std-ref">the scautopick module</span></a></p>
+</div>
 </section>
 <section id="internal-links">
 <span id="documentation-style-guide-links"></span><h3>Internal links<a class="headerlink" href="#internal-links" title="Permalink to this heading">¶</a></h3>
 <p>Create links to sections and subsections within and to figures  the text which can be referenced.
 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.</p>
-<p>Link within this documentation to the section on headings:</p>
+<p>Create a label within this <cite>SeisComP</cite> documentation to the section on headings:</p>
 <div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_documentation_style_guide_headings:</span>
 </pre></div>
 </div>
-<p>Reference:</p>
-<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="na">:ref:</span><span class="nv">`short name &lt;documentation_style_guide_headings&gt;`</span>
+<p>and refer to the lable within the text:</p>
+<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="na">:ref:</span><span class="nv">`link to this section &lt;documentation_style_guide_headings&gt;`</span>
 </pre></div>
 </div>
-<p>Result: <a class="reference internal" href="#documentation-style-guide-headings"><span class="std std-ref">short name</span></a></p>
+<p>Result: <a class="reference internal" href="#documentation-style-guide-headings"><span class="std std-ref">link to this section</span></a></p>
 </section>
 <section id="external-links-and-references">
 <h3>External links and references<a class="headerlink" href="#external-links-and-references" title="Permalink to this heading">¶</a></h3>
@ -274,8 +337,8 @@ directive</p>
 <span class="na">:cite:t:</span><span class="nv">`seiscomp`</span>
 </pre></div>
 </div>
-<p>which results in <span id="id1">[<a class="reference internal" href="references.html#id257" title="Helmholtz-Centre Potsdam - GFZ German Research Centre for Geosciences and gempa GmbH. The SeisComP seismological software package. GFZ Data Services. 2008. URL: https://www.seiscomp.de, doi:10.5880/GFZ.2.4.2020.003.">67</a>]</span> and
-<span id="id2">Helmholtz-Centre Potsdam - GFZ German Research Centre for Geosciences and gempa GmbH [<a class="reference internal" href="references.html#id257" title="Helmholtz-Centre Potsdam - GFZ German Research Centre for Geosciences and gempa GmbH. The SeisComP seismological software package. GFZ Data Services. 2008. URL: https://www.seiscomp.de, doi:10.5880/GFZ.2.4.2020.003.">67</a>]</span> within the documentation HTML text.</p>
+<p>which results in <span id="id1">[<a class="reference internal" href="references.html#id290" title="Helmholtz-Centre Potsdam - GFZ German Research Centre for Geosciences and gempa GmbH. The SeisComP seismological software package. GFZ Data Services. 2008. URL: https://www.seiscomp.de, doi:10.5880/GFZ.2.4.2020.003.">76</a>]</span> and
+<span id="id2">Helmholtz-Centre Potsdam - GFZ German Research Centre for Geosciences and gempa GmbH [<a class="reference internal" href="references.html#id290" title="Helmholtz-Centre Potsdam - GFZ German Research Centre for Geosciences and gempa GmbH. The SeisComP seismological software package. GFZ Data Services. 2008. URL: https://www.seiscomp.de, doi:10.5880/GFZ.2.4.2020.003.">76</a>]</span> within the documentation HTML text.</p>
 </li>
 </ol>
 <p>If you really cannot avoid URLs in RST files, then you may link them to some
@ -354,6 +417,67 @@ Make sensible use of it!</p>
 </li>
 </ul>
 </section>
+<section id="images">
+<span id="documentation-style-guide-images"></span><h3>Images<a class="headerlink" href="#images" title="Permalink to this heading">¶</a></h3>
+<section id="code-implementation">
+<h4>Code implementation<a class="headerlink" href="#code-implementation" title="Permalink to this heading">¶</a></h4>
+<p>The images will be moved to the correct location during the documentation build.</p>
+<ul class="simple">
+<li><p>Place image files in a suitable sub-directory of <code class="file docutils literal notranslate"><span class="pre">descriptions/media</span></code>.</p></li>
+<li><p>Add images with fixed width.</p></li>
+<li><p>Define image alignment.</p></li>
+<li><p>Add image captions.</p></li>
+<li><p>Store images in a separate directory of below the directory where the
+documentation is kept.</p></li>
+</ul>
+<p>Example for an image which can be enlarge by mouse click:</p>
+<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">figure</span><span class="p">::</span>  media/image.png
+   <span class="nc">:alt:</span> image one
+   <span class="nc">:width:</span> 10cm
+   <span class="nc">:align:</span> center
+
+   Image one.
+</pre></div>
+</div>
+<p>Example for images in two columns which cannot be enlarged. Up to 4 columns are possible.
+Compare with the <a class="reference internal" href="concepts/configuration.html#concepts-configuration-configs"><span class="std std-ref">concept section on configuration</span></a>:</p>
+<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">raw</span><span class="p">::</span> html
+
+<span class="nt">&lt;div class=&quot;two column layout&quot;&gt;</span>
+
+<span class="p">..</span> <span class="ow">figure</span><span class="p">::</span> ../media/scconfig_no_bindings.png
+   <span class="nc">:alt:</span> scconfig: bindings configurations
+
+   scconfig modules panel indicating that no bindings can be configured.
+
+<span class="p"> ..</span> <span class="ow">figure</span><span class="p">::</span> ../media/scconfig_has_bindings.png
+    <span class="nc">:alt:</span> scconfig: no bindings configurations
+
+    scconfig modules panel indicating that bindings can be configured.
+
+<span class="p"> ..</span> <span class="ow">raw</span><span class="p">::</span> html
+
+ &lt;/div&gt;
+</pre></div>
+</div>
+</section>
+<section id="image-style-and-format">
+<h4>Image style and format<a class="headerlink" href="#image-style-and-format" title="Permalink to this heading">¶</a></h4>
+<ul class="simple">
+<li><p>Images shall be informative.</p></li>
+<li><p>Images must not have any offensive or inappropriate content.</p></li>
+<li><p>Use PNG format.</p></li>
+<li><p>Make the important image details readable at the normal image size without enlargement.</p></li>
+<li><p>Images shall be optimized for file size.</p></li>
+<li><p>Images should have a frame, e.g. a window frame.</p></li>
+<li><p>Avoid private information on images.</p></li>
+<li><p>Do not show desktop background unless required.</p></li>
+<li><p>Images from <cite>SeisComP</cite> GUIs can be screenshots.</p></li>
+<li><p>Do not create screenshots from applications started remotely with X-forwarding.
+X-forwarding may distort the application features.</p></li>
+</ul>
+</section>
+</section>
 </section>
 <section id="english-language">
 <h2>English Language<a class="headerlink" href="#english-language" title="Permalink to this heading">¶</a></h2>
@ -398,8 +522,8 @@ See the <a class="reference external" href="https://english.stackexchange.com/qu
 </li>
 <li><p>Case:</p>
 <ul class="simple">
-<li><p>SEED, miniSEED (miniSEED in <span id="id3"><em>libmseed - The miniSEED data format library</em> [<a class="reference internal" href="references.html#id147" title="libmseed - The miniSEED data format library. GitHub, 2017. URL: https://github.com/EarthScope/libmseed/wiki.">32</a>]</span>, or MiniSEED,
-but Mini-SEED appears in Appendix G of the <span id="id4"><em>SEED Reference Manual</em> [<a class="reference internal" href="references.html#id252" title="SEED Reference Manual. USGS, 2012. URL: http://www.fdsn.org/pdf/SEEDManual_V2.4.pdf.">31</a>]</span>.)</p></li>
+<li><p>SEED, miniSEED (miniSEED in <span id="id3"><em>libmseed - The miniSEED data format library</em> [<a class="reference internal" href="references.html#id176" title="libmseed - The miniSEED data format library. GitHub, 2017. URL: https://github.com/EarthScope/libmseed/wiki.">40</a>]</span>, or MiniSEED,
+but Mini-SEED appears in Appendix G of the <span id="id4"><em>SEED Reference Manual</em> [<a class="reference internal" href="references.html#id285" title="SEED Reference Manual. USGS, 2012. URL: http://www.fdsn.org/pdf/SEEDManual_V2.4.pdf.">39</a>]</span>.)</p></li>
 <li><p>Ctrl+S for ‘control’ key plus ‘s’.</p></li>
 <li><p>MySQL, PostgreSQL, MariaDB</p></li>
 </ul>
@ -413,64 +537,6 @@ but Mini-SEED appears in Appendix G of the <span id="id4"><em>SEED Reference Man
 </li>
 </ul>
 </section>
-<section id="adding-images">
-<span id="documentation-style-guide-images"></span><h2>Adding Images<a class="headerlink" href="#adding-images" title="Permalink to this heading">¶</a></h2>
-<section id="code-implementation">
-<h3>Code implementation<a class="headerlink" href="#code-implementation" title="Permalink to this heading">¶</a></h3>
-<ul class="simple">
-<li><p>Add images with fixed width.</p></li>
-<li><p>Add image captions.</p></li>
-<li><p>Store images in a separate directory of below the directory where the
-documentation is kept.</p></li>
-</ul>
-<p>Example for an image which can be enlarge by mouse click:</p>
-<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">figure</span><span class="p">::</span>  media/image.png
-   <span class="nc">:alt:</span> image one
-   <span class="nc">:width:</span> 10cm
-   <span class="nc">:align:</span> center
-
-   Image one.
-</pre></div>
-</div>
-<p>Example for images in two columns which cannot be enlarged. Up to 4 columns are possible.
-Compare with the <a class="reference internal" href="concepts/configuration.html#concepts-configuration-configs"><span class="std std-ref">concept section on configuration</span></a>:</p>
-<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">raw</span><span class="p">::</span> html
-
-<span class="nt">&lt;div class=&quot;two column layout&quot;&gt;</span>
-
-<span class="p">..</span> <span class="ow">figure</span><span class="p">::</span> ../media/scconfig_no_bindings.png
-   <span class="nc">:alt:</span> scconfig: bindings configurations
-
-   scconfig modules panel indicating that no bindings can be configured.
-
-<span class="p"> ..</span> <span class="ow">figure</span><span class="p">::</span> ../media/scconfig_has_bindings.png
-    <span class="nc">:alt:</span> scconfig: no bindings configurations
-
-    scconfig modules panel indicating that bindings can be configured.
-
-<span class="p"> ..</span> <span class="ow">raw</span><span class="p">::</span> html
-
- &lt;/div&gt;
-</pre></div>
-</div>
-</section>
-<section id="image-style-and-format">
-<h3>Image style and format<a class="headerlink" href="#image-style-and-format" title="Permalink to this heading">¶</a></h3>
-<ul class="simple">
-<li><p>Images shall be informative.</p></li>
-<li><p>Images must not have any offensive or inappropriate content.</p></li>
-<li><p>Use PNG format.</p></li>
-<li><p>Make the important image details readable at the normal image size without enlargement.</p></li>
-<li><p>Images shall be optimized for file size.</p></li>
-<li><p>Images should have a frame, e.g. a window frame.</p></li>
-<li><p>Avoid private information on images.</p></li>
-<li><p>Do not show desktop background unless required.</p></li>
-<li><p>Images from <cite>SeisComP</cite> GUIs can be screenshots.</p></li>
-<li><p>Do not create screenshots from applications started remotely with X-forwarding.
-X-forwarding may distort the application features.</p></li>
-</ul>
-</section>
-</section>
 <section id="references">
 <h2>References<a class="headerlink" href="#references" title="Permalink to this heading">¶</a></h2>
 <aside class="footnote-list brackets">
@ -509,18 +575,19 @@ X-forwarding may distort the application features.</p></li>
 <li><a class="reference internal" href="#general-principles">General principles</a></li>
 <li><a class="reference internal" href="#section-and-headings">Section and headings</a></li>
 <li><a class="reference internal" href="#lists">Lists</a></li>
-<li><a class="reference internal" href="#other-markup-tools-and-conventions">Other markup tools and conventions</a></li>
+<li><a class="reference internal" href="#tables">Tables</a></li>
+<li><a class="reference internal" href="#other-tools-and-conventions">Other tools and conventions</a></li>
 <li><a class="reference internal" href="#internal-links">Internal links</a></li>
 <li><a class="reference internal" href="#external-links-and-references">External links and references</a></li>
 <li><a class="reference internal" href="#text-boxes">Text boxes</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#english-language">English Language</a></li>
-<li><a class="reference internal" href="#adding-images">Adding Images</a><ul>
+<li><a class="reference internal" href="#images">Images</a><ul>
 <li><a class="reference internal" href="#code-implementation">Code implementation</a></li>
 <li><a class="reference internal" href="#image-style-and-format">Image style and format</a></li>
 </ul>
 </li>
+</ul>
+</li>
+<li><a class="reference internal" href="#english-language">English Language</a></li>
 <li><a class="reference internal" href="#references">References</a></li>
 </ul>
 </li>
@ -556,7 +623,7 @@ X-forwarding may distort the application features.</p></li>
        </a>
        <div class="stretched align-center fitted content">
          <div>
-		  Version <b>6.9.0</b> Release
+		  Version <b>7.0.0</b> Development
          </div>
            <div class="copyright">
              Copyright &copy; gempa GmbH, GFZ Potsdam.