572 lines
28 KiB
HTML
572 lines
28 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
|
||
<title>Style Guide for Documentation — SeisComP Release 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" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/seiscomp.css?v=c6da7ce6" />
|
||
<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 src="../_static/doctools.js?v=888ff710"></script>
|
||
<script src="../_static/sphinx_highlight.js?v=4825356b"></script>
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="next" title="Coding Conventions" href="coding-conventions.html" />
|
||
<link rel="prev" title="Contributing Documentation" href="contributing-docs.html" />
|
||
</head>
|
||
<body>
|
||
<div class="header">
|
||
<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>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="nav">
|
||
<div class="container">
|
||
<div class="content"><a class="pull-right" id="sidebar-toggle">TOC</a>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<ul>
|
||
<li class="right">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">
|
||
index
|
||
</a>
|
||
</li>
|
||
<li class="right">
|
||
<a href="coding-conventions.html" title="Coding Conventions"
|
||
accesskey="N">
|
||
next
|
||
</a>
|
||
</li>
|
||
<li class="right">
|
||
<a href="contributing-docs.html" title="Contributing Documentation"
|
||
accesskey="P">
|
||
previous
|
||
</a>
|
||
</li>
|
||
<li class="nav-item nav-item-0">
|
||
<a href="../index.html">Home</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="container">
|
||
<div class="fitted content" id="anchors-container">
|
||
<div class="body" role="main">
|
||
|
||
<section id="style-guide-for-documentation">
|
||
<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>
|
||
<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>
|
||
</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>
|
||
</section>
|
||
<section id="documentation-syntax">
|
||
<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
|
||
the command, introduced with one or more headings.
|
||
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>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
|
||
appear on their own line.</p>
|
||
</li>
|
||
</ul>
|
||
</section>
|
||
<section id="section-and-headings">
|
||
<span id="documentation-style-guide-headings"></span><h3>Section and headings<a class="headerlink" href="#section-and-headings" title="Permalink to this heading">¶</a></h3>
|
||
<p>Module description files do <em>not</em> require top-level headings, as the
|
||
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>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Level</p></th>
|
||
<th class="head"><p>Mark up beneath heading text</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p>1</p></td>
|
||
<td><p>‘ ==== ‘</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>2</p></td>
|
||
<td><p>“ —- “</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>3</p></td>
|
||
<td><p>‘ ~~~~ ‘</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>4</p></td>
|
||
<td><p>‘ ^^^^ ‘</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Use Title Case for headings within a section, and make only the first letter uppercase for subheadings.
|
||
Higher levels, marked up with asterisks, are used for sections of the documentation.</p>
|
||
<p><strong>Example:</strong></p>
|
||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>Level<span class="w"> </span><span class="m">1</span><span class="w"> </span><span class="nv">Title</span>
|
||
<span class="o">=============</span>
|
||
|
||
Some<span class="w"> </span>text.
|
||
|
||
|
||
Level<span class="w"> </span><span class="m">2</span><span class="w"> </span>title
|
||
-------------
|
||
|
||
Some<span class="w"> </span>text
|
||
</pre></div>
|
||
</div>
|
||
<p>Parts such as Examples are marked in <strong>bold</strong>.</p>
|
||
<p>However notes and figures should use the appropriate RST directive, and don’t require their own headings.</p>
|
||
<ul class="simple">
|
||
<li><p>One blank line below headings is enough.</p></li>
|
||
<li><p>Two lines above are often used, and this looks better than one.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="lists">
|
||
<h3>Lists<a class="headerlink" href="#lists" title="Permalink to this heading">¶</a></h3>
|
||
<p>Use numbered or unnumbered lists at several levels.</p>
|
||
<ul class="simple">
|
||
<li><p>Start list items at the first level with a capital letter. End them with a full stop.</p></li>
|
||
<li><p>Use lower-case letters for all other levels. End them with a full stop.</p></li>
|
||
</ul>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="m">#.</span> Item 1.
|
||
<span class="m">#.</span> Item 2.
|
||
<span class="m">*</span> subitem 1.
|
||
<span class="m">#.</span> subsubitem 1.
|
||
<span class="m">#.</span> subsubitem 1.
|
||
<span class="m">*</span> subitem 2.
|
||
</pre></div>
|
||
</div>
|
||
<p><strong>Result:</strong></p>
|
||
<ol class="arabic simple">
|
||
<li><p>Item 1.</p></li>
|
||
<li><p>Item 2.</p>
|
||
<ul class="simple">
|
||
<li><p>subitem 1.</p>
|
||
<ol class="loweralpha simple">
|
||
<li><p>subsubitem 1.</p></li>
|
||
<li><p>subsubitem 2.</p></li>
|
||
</ol>
|
||
</li>
|
||
<li><p>subitem 2.</p></li>
|
||
</ul>
|
||
</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>
|
||
<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>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">code-block</span><span class="p">::</span> <span class="k">sh</span>
|
||
|
||
<span class="ch">#!/bin/bash</span>
|
||
<span class="nb">echo</span><span class="w"> </span><span class="nv">$SEISCOMP_ROOT</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Result:</p>
|
||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span>
|
||
<span class="nb">echo</span><span class="w"> </span><span class="nv">$SEISCOMP_ROOT</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><strong>Configuration parameters:</strong> Configuration values have a special
|
||
syntax. Use the ‘:confval:’ indicator for referencing a module configuration
|
||
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>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>
|
||
</li>
|
||
<li><p><strong>Command-line options:</strong> Command-line options have a special
|
||
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>
|
||
</li>
|
||
<li><p><strong>Configuration files:</strong> Use the reST ‘:file:’ indicator to refer to files such
|
||
as configuration files:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="na">:file:</span><span class="nv">`$SEISCOMP_ROOT/etc/scautopick.cfg`</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Result: <code class="file docutils literal notranslate"><span class="pre">$SEISCOMP_ROOT/etc/scautopick.cfg</span></code></p>
|
||
</li>
|
||
<li><p><strong>Programs:</strong> Use the reST ‘:program:’ indicator for <cite>SeisComP</cite> programs:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="na">:program:</span><span class="nv">`scautopick`</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Result: <strong class="program">scautopick</strong></p>
|
||
</li>
|
||
<li><p><strong>References:</strong> Use the reST ‘:ref:’ indicator for cross referencing <cite>SeisComP</cite>
|
||
module documentation pages:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="na">:ref:</span><span class="nv">`scautopick`</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Result: <a class="reference internal" href="../apps/scautopick.html#scautopick"><span class="std std-ref">scautopick</span></a></p>
|
||
</li>
|
||
<li><p><strong>Glossary:</strong> Use the reST ‘:term:’ indicator for referencing terms in the
|
||
<cite>SeisComP</cite> <a class="reference internal" href="glossary.html#glossary"><span class="std std-ref">Glossary</span></a>:</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="na">:term:</span><span class="nv">`magnitude`</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Result: <a class="reference internal" href="glossary.html#term-magnitude"><span class="xref std std-term">magnitude</span></a></p>
|
||
</li>
|
||
</ul>
|
||
</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>
|
||
<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 <documentation_style_guide_headings>`</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>
|
||
</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>
|
||
<p>Preferably you do not show full citations or URLs for literature or
|
||
external web sites within the text but make references which
|
||
are listed in the section <a class="reference internal" href="references.html#sec-references"><span class="std std-ref">References</span></a>. Procedure:</p>
|
||
<ol class="arabic">
|
||
<li><p>Add publications, external URLs, etc. as complete citation
|
||
entries to the reference list <code class="file docutils literal notranslate"><span class="pre">doc/base/references.bib</span></code>
|
||
in the base <cite>SeisComP</cite> <a class="reference internal" href="build.html#build"><span class="std std-ref">repository on Github</span></a>.</p></li>
|
||
<li><p>Cite documents within the RST file using the <em>cite</em>
|
||
directive</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="na">:cite:p:</span><span class="nv">`seiscomp`</span>
|
||
<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>
|
||
</li>
|
||
</ol>
|
||
<p>If you really cannot avoid URLs in RST files, then you may link them to some
|
||
text like</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="s">`SeisComP forum </span><span class="si"><https://forum.seiscomp.de/></span><span class="s">`_</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>resulting in <a class="reference external" href="https://forum.seiscomp.de/">SeisComP forum</a>.</p>
|
||
<p>Alternatively you may generate reference in a <em>Reference</em> sections as</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">References</span>
|
||
<span class="gh">==========</span>
|
||
|
||
<span class="p">..</span> <span class="ow">target-notes</span><span class="p">::</span>
|
||
|
||
<span class="p">..</span> <span class="nt">_`discussion` :</span> https://english.stackexchange.com/questions/65630/you-should-be-well-organised-or-you-should-be-well-organised
|
||
</pre></div>
|
||
</div>
|
||
<p>and then cite it within the text as</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="s">`discussion`_</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>which results in <a class="reference external" href="https://english.stackexchange.com/questions/65630/you-should-be-well-organised-or-you-should-be-well-organised">discussion</a> <a class="footnote-reference brackets" href="#id5" id="id6" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>.</p>
|
||
</section>
|
||
<section id="text-boxes">
|
||
<h3>Text boxes<a class="headerlink" href="#text-boxes" title="Permalink to this heading">¶</a></h3>
|
||
<p>You may emphasize information within the text as text boxes to stand out at different levels.
|
||
Make sensible use of it!</p>
|
||
<ul>
|
||
<li><p>Hints</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">hint</span><span class="p">::</span>
|
||
|
||
This adds a useful hint.
|
||
</pre></div>
|
||
</div>
|
||
<p>Result:</p>
|
||
<div class="admonition hint">
|
||
<p class="admonition-title">Hint</p>
|
||
<p>This adds a useful hint.</p>
|
||
</div>
|
||
</li>
|
||
<li><p>Notes</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">note</span><span class="p">::</span>
|
||
|
||
This adds an extra note.
|
||
</pre></div>
|
||
</div>
|
||
<p>Result:</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This adds an extra note.</p>
|
||
</div>
|
||
</li>
|
||
<li><p>Alerts</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">caution</span><span class="p">::</span>
|
||
|
||
This adds a heads-up alert.
|
||
</pre></div>
|
||
</div>
|
||
<p>Result:</p>
|
||
<div class="admonition caution">
|
||
<p class="admonition-title">Caution</p>
|
||
<p>This adds a heads-up alert.</p>
|
||
</div>
|
||
</li>
|
||
<li><p>Warnings</p>
|
||
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">warning</span><span class="p">::</span>
|
||
|
||
This adds an important warning.
|
||
</pre></div>
|
||
</div>
|
||
<p>Result:</p>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>This adds an important warning.</p>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
<section id="english-language">
|
||
<h2>English Language<a class="headerlink" href="#english-language" title="Permalink to this heading">¶</a></h2>
|
||
<ul class="simple">
|
||
<li><p>SeisComP (capital P), not SeisComP 3 or SC3.</p></li>
|
||
<li><p><cite>SeisComP</cite> module names are proper nouns, even though written with lower case.
|
||
Thus they do not need an article.</p>
|
||
<ul>
|
||
<li><p>Correct: “Although <strong class="program">scmaster</strong> receives a message”</p></li>
|
||
<li><p>Incorrect: “Although the scmaster receives a message…”</p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>A sentence may begin with a lower case module name e.g. “scmaster has five modes…”
|
||
avoiding this: “The <strong class="program">scmaster</strong> module has…”</p>
|
||
<ul>
|
||
<li><p>Word separation:</p>
|
||
<ul class="simple">
|
||
<li><p>Separate words:
|
||
base class, wave number, time span</p></li>
|
||
<li><p>One word:
|
||
aftershock, foreshock, <em>and mainshock too</em>,
|
||
bandpass, eigenperiod etc., metadata, standalone, username, workflow, waveform</p></li>
|
||
<li><p>Difficult:
|
||
high-pass filter; command line; command-line parameter</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p>Hyphenation for compound adjectives: yes, before a noun; after verb to be is harder.
|
||
See the <a class="reference external" href="https://english.stackexchange.com/questions/65630/you-should-be-well-organised-or-you-should-be-well-organised">discussion</a> <a class="footnote-reference brackets" href="#id5" id="id7" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>, e.g.:</p>
|
||
<ul class="simple">
|
||
<li><p>Use command-line parameters</p></li>
|
||
<li><p>Type on the command line</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p>Spelling:</p>
|
||
<p>Use American English:</p>
|
||
<ul class="simple">
|
||
<li><p>With ‘z’: digitizer, realize, visualize, synchronize, behavior, color.</p></li>
|
||
<li><p>With ‘s’: license.</p></li>
|
||
<li><p>Center, data center.</p></li>
|
||
</ul>
|
||
</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>Ctrl+S for ‘control’ key plus ‘s’.</p></li>
|
||
<li><p>MySQL, PostgreSQL, MariaDB</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p>Abbreviations:</p>
|
||
<ul class="simple">
|
||
<li><p>e.g., i.e.</p></li>
|
||
<li><p>STA, LTA, STA/LTA detector</p></li>
|
||
<li><p>TAR file</p></li>
|
||
</ul>
|
||
</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"><div class="two column layout"></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
|
||
|
||
</div>
|
||
</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">
|
||
<aside class="footnote brackets" id="id5" role="doc-footnote">
|
||
<span class="label"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></span>
|
||
<span class="backrefs">(<a role="doc-backlink" href="#id6">1</a>,<a role="doc-backlink" href="#id7">2</a>)</span>
|
||
<p><a class="reference external" href="https://english.stackexchange.com/questions/65630/you-should-be-well-organised-or-you-should-be-well-organised">https://english.stackexchange.com/questions/65630/you-should-be-well-organised-or-you-should-be-well-organised</a></p>
|
||
</aside>
|
||
</aside>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div id="anchors-bottom"></div>
|
||
</div>
|
||
|
||
<div class="sidebar" role="navigation" aria-label="main navigation">
|
||
<div id="anchors-top"></div>
|
||
<div id="anchors" class="content">
|
||
<div id="searchbox" style="display: none" role="search">
|
||
<h3 id="searchlabel">Quick search</h3>
|
||
<div class="searchformwrapper">
|
||
<form class="search" action="../search.html" method="get">
|
||
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
</div>
|
||
<script>document.getElementById('searchbox').style.display = "block"</script>
|
||
<div>
|
||
<h3><a href="../index.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">Style Guide for Documentation</a><ul>
|
||
<li><a class="reference internal" href="#file-layout">File Layout</a></li>
|
||
<li><a class="reference internal" href="#documentation-syntax">Documentation Syntax</a><ul>
|
||
<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="#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="#code-implementation">Code implementation</a></li>
|
||
<li><a class="reference internal" href="#image-style-and-format">Image style and format</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#references">References</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="contributing-docs.html"
|
||
title="previous chapter">Contributing Documentation</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="coding-conventions.html"
|
||
title="next chapter">Coding Conventions</a></p>
|
||
</div>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../_sources/base/style-guide.rst.txt"
|
||
rel="nofollow">Show Source</a></li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="footer">
|
||
<div class="container">
|
||
<div class="horizontal layout content">
|
||
<a class="fade-in" href="https://www.gempa.de" target="_blank">
|
||
<img class="brand" src="../_static/brands/gempa.svg"/>
|
||
</a>
|
||
<div class="stretched align-center fitted content">
|
||
<div>
|
||
Version <b>6.9.0</b> Release
|
||
</div>
|
||
<div class="copyright">
|
||
Copyright © gempa GmbH, GFZ Potsdam.
|
||
</div>
|
||
</div>
|
||
<a class="fade-in" href="https://www.gfz-potsdam.de" target="_blank">
|
||
<img class="brand" src="../_static/brands/gfz.svg"/>
|
||
</a>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</body>
|
||
</html> |