<spanid="id1"></span><h1>reST primer<aclass="headerlink"href="#rest-primer"title="Permalink to this headline">¶</a></h1>
<divclass="sidebar">
<pclass="sidebar-title"><aclass="reference external"href="https://en.wikipedia.org/wiki/KISS_principle">KISS</a> and <aclass="reference external"href="https://docs.python-guide.org/writing/style/">readability</a></p>
<p>Instead of defining more and more roles, we at searx encourage our
contributors to follow principles like <aclass="reference external"href="https://en.wikipedia.org/wiki/KISS_principle">KISS</a> and <aclass="reference external"href="https://docs.python-guide.org/writing/style/">readability</a>.</p>
</div>
<p>We at searx are using reStructuredText (aka <aclass="reference external"href="https://docutils.sourceforge.io/rst.html">reST</a>) markup for all kind of
documentation, with the builders from the <aclass="reference external"href="http://www.sphinx-doc.org">Sphinx</a> project a HTML output is
<p>The source files of Searx’s documentation are located at <aclass="reference external"href="https://github.com/return42/searx/blob/filtron/docs">git://docs</a>. Sphinx
assumes source files to be encoded in UTF-8 by defaul. Run <aclass="reference internal"href="contribution_guide.html#make-docs-live"><spanclass="std std-ref">make docs-live</span></a> to build HTML while editing.</p>
<p><aclass="reference external"href="http://www.sphinx-doc.org">Sphinx</a> and <aclass="reference external"href="https://docutils.sourceforge.io/rst.html">reST</a> have their place in the python ecosystem. Over that reST is
used in popular projects, e.g the Linux kernel documentation <aclass="reference external"href="https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html">[kernel doc]</a>.</p>
<divclass="sidebar">
<pclass="sidebar-title">Content matters</p>
<p>The <aclass="reference external"href="https://docs.python-guide.org/writing/style/">readability</a> of the reST sources has its value, therefore we recommend to
make sparse usage of reST markup / .. content matters!</p>
</div>
<p><strong>reST</strong> is a plaintext markup language, its markup is <em>mostly</em> intuitive and
you will not need to learn much to produce well formed articles with. I use the
word <em>mostly</em>: like everything in live, reST has its advantages and
disadvantages, some markups feel a bit grumpy (especially if you are used to
other plaintext markups).</p>
<divclass="section"id="soft-skills">
<h2><aclass="toc-backref"href="#id15">Soft skills</a><aclass="headerlink"href="#soft-skills"title="Permalink to this headline">¶</a></h2>
<p>Before going any deeper into the markup let’s face on some <strong>soft skills</strong> a
trained author brings with, to reach a well feedback from readers:</p>
<ulclass="simple">
<li><p>Documentation is dedicated to an audience and answers questions from the
audience point of view.</p></li>
<li><p>Don’t detail things which are general knowledge from the audience point of
view.</p></li>
<li><p>Limit the subject, use cross links for any further reading.</p></li>
<p>To be more concrete what a <em>point of view</em> means. In the (<aclass="reference external"href="https://github.com/return42/searx/blob/filtron/docs">git://docs</a>)
<dt>User’s POV: <aclass="reference external"href="https://github.com/return42/searx/blob/filtron/docs/user">git://docs/user</a></dt><dd><p>A typical user knows about search engines and might have heard about
<dt>Admin’s POV: <aclass="reference external"href="https://github.com/return42/searx/blob/filtron/docs/admin">git://docs/admin</a></dt><dd><p>A typical Admin knows about setting up services on a linux system, but he does
<dt>Developer’s POV: <aclass="reference external"href="https://github.com/return42/searx/blob/filtron/docs/dev">git://docs/dev</a></dt><dd><p>Depending on the <aclass="reference external"href="https://docs.python-guide.org/writing/style/">readability</a> of code, a typical developer is able to read and
understand source code. Describe what a item aims to do (e.g. a function).
If the chronological order matters, describe it. Name the <em>out-of-limits
conditions</em> and all the side effects a external developer will not know.</p>
</dd>
</dl>
</div>
<divclass="section"id="basic-inline-markup">
<spanid="rest-inline-markup"></span><h2><aclass="toc-backref"href="#id16">Basic inline markup</a><aclass="headerlink"href="#basic-inline-markup"title="Permalink to this headline">¶</a></h2>
<caption><spanclass="caption-number">Table 3 </span><spanclass="caption-text">basic inline markup</span><aclass="headerlink"href="#id4"title="Permalink to this table">¶</a></caption>
<spanid="rest-basic-structure"></span><h2><aclass="toc-backref"href="#id17">Basic article structure</a><aclass="headerlink"href="#basic-article-structure"title="Permalink to this headline">¶</a></h2>
<p>The basic structure of an article makes use of heading adornments to markup
chapter, sections and subsections.</p>
<divclass="section"id="rest-template">
<spanid="id2"></span><h3><aclass="toc-backref"href="#id18">reST template</a><aclass="headerlink"href="#rest-template"title="Permalink to this headline">¶</a></h3>
<h2><aclass="toc-backref"href="#id20">Anchors & Links</a><aclass="headerlink"href="#anchors-links"title="Permalink to this headline">¶</a></h2>
<divclass="section"id="anchors">
<spanid="rest-anchor"></span><h3><aclass="toc-backref"href="#id21">Anchors</a><aclass="headerlink"href="#anchors"title="Permalink to this headline">¶</a></h3>
<p>To refer a point in the documentation a anchor is needed. The <aclass="reference internal"href="#rest-template"><spanclass="std std-ref">reST
template</span></a> shows an example where a chapter titled <em>“Chapters”</em>
gets an anchor named <codeclass="docutils literal notranslate"><spanclass="pre">chapter</span><spanclass="pre">title</span></code>. Another example from <em>this</em> document,
where the anchor named <codeclass="docutils literal notranslate"><spanclass="pre">reST</span><spanclass="pre">anchor</span></code>:</p>
To refer a point in the documentation a anchor is needed ...
</pre></div>
</div>
<p>To refer anchors use the <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref">ref role</a> markup:</p>
<divclass="highlight-reST notranslate"><divclass="highlight"><pre><span></span>Visit chapter <spanclass="na">:ref:</span><spanclass="nv">`reST anchor`</span>. Or set hyperlink text manualy :ref:`foo
<p>Visist chapter <aclass="reference internal"href="#rest-anchor"><spanclass="std std-ref">Anchors</span></a>. Or set hyperlink text manualy <aclass="reference internal"href="#rest-anchor"><spanclass="std std-ref">foo
bar</span></a>.</p>
</div>
</div>
<divclass="section"id="link-ordinary-url">
<spanid="rest-ordinary-ref"></span><h3><aclass="toc-backref"href="#id22">Link ordinary URL</a><aclass="headerlink"href="#link-ordinary-url"title="Permalink to this headline">¶</a></h3>
<p>If you need to reference external URLs use <em>named</em> hyperlinks to maintain
readability of reST sources. Here is a example taken from <em>this</em> article:</p>
<divclass="highlight-reST notranslate"><divclass="highlight"><pre><span></span><spanclass="p">..</span><spanclass="nt">_Sphinx Field Lists:</span>
<p>With the <em>named</em> hyperlink <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html">Sphinx Field Lists</a>, the raw text is much more
readable.</p>
<p>And this shows the alternative (less readable) hyperlink markup <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html">Sphinx Field
Lists</a>.</p>
</div>
</div>
<divclass="section"id="smart-refs">
<spanid="rest-smart-ref"></span><h3><aclass="toc-backref"href="#id23">Smart refs</a><aclass="headerlink"href="#smart-refs"title="Permalink to this headline">¶</a></h3>
<p>With the power of <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html">sphinx.ext.extlinks</a> and <aclass="reference external"href="http://www.sphinx-doc.org/en/stable/ext/intersphinx.html">intersphinx</a> referencing external
<caption><spanclass="caption-number">Table 4 </span><spanclass="caption-text">smart refs with <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html">sphinx.ext.extlinks</a> and <aclass="reference external"href="http://www.sphinx-doc.org/en/stable/ext/intersphinx.html">intersphinx</a></span><aclass="headerlink"href="#id5"title="Permalink to this table">¶</a></caption>
<p>Intersphinx is configured in <aclass="reference external"href="https://github.com/return42/searx/blob/filtron/docs/conf.py">git://docs/conf.py</a>:</p>
<h2><aclass="toc-backref"href="#id24">Literal blocks</a><aclass="headerlink"href="#literal-blocks"title="Permalink to this headline">¶</a></h2>
<p>The simplest form of <aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#literal-blocks">literal-blocks</a> is a indented block introduced by
two colons (<codeclass="docutils literal notranslate"><spanclass="pre">::</span></code>). For highlighting use <aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#highlight">highlight</a> or <aclass="reference internal"href="#rest-code"><spanclass="std std-ref">code-block</span></a> directive. To include literals from external files use directive
<spanid="id3"></span><h3><aclass="toc-backref"href="#id25"><codeclass="docutils literal notranslate"><spanclass="pre">::</span></code></a><aclass="headerlink"href="#rest-literal"title="Permalink to this headline">¶</a></h3>
<spanid="rest-code"></span><h3><aclass="toc-backref"href="#id26"><codeclass="docutils literal notranslate"><spanclass="pre">code-block</span></code></a><aclass="headerlink"href="#code-block"title="Permalink to this headline">¶</a></h3>
<divclass="sidebar">
<pclass="sidebar-title">Syntax highlighting</p>
<p>is handled by <aclass="reference external"href="https://pygments.org/languages/">pygments</a>.</p>
<p>The <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block"title="(in Sphinx v4.0.0+/adad0e62b)"><codeclass="xref rst rst-dir docutils literal notranslate"><spanclass="pre">code-block</span></code></a> directive is a variant of the <aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#code">code</a> directive
<divclass="highlight-reST notranslate"><divclass="highlight"><pre><span></span>The URL <spanclass="s">``/stats``</span> handle is shown in <spanclass="na">:ref:</span><spanclass="nv">`stats-handle`</span>
<divclass="code-block-caption"><spanclass="caption-number">Listing 1 </span><spanclass="caption-text">python code block</span><aclass="headerlink"href="#stats-handle"title="Permalink to this code">¶</a></div>
<h2><aclass="toc-backref"href="#id27">Unicode substitution</a><aclass="headerlink"href="#unicode-substitution"title="Permalink to this headline">¶</a></h2>
<spanid="rest-roles"></span><h2><aclass="toc-backref"href="#id28">Roles</a><aclass="headerlink"href="#roles"title="Permalink to this headline">¶</a></h2>
<p>A <em>custom interpreted text role</em> (<aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#roles">ref</a>) is an inline piece of
explicit markup. It signifies that that the enclosed text should be interpreted
<caption><spanclass="caption-number">Table 5 </span><spanclass="caption-text">smart refs with <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html">sphinx.ext.extlinks</a> and <aclass="reference external"href="http://www.sphinx-doc.org/en/stable/ext/intersphinx.html">intersphinx</a></span><aclass="headerlink"href="#id6"title="Permalink to this table">¶</a></caption>
<h2><aclass="toc-backref"href="#id29">Figures & Images</a><aclass="headerlink"href="#figures-images"title="Permalink to this headline">¶</a></h2>
<divclass="sidebar">
<pclass="sidebar-title">Image processing</p>
<p>With the directives from <aclass="reference external"href="https://return42.github.io/linuxdoc/linuxdoc-howto/kfigure.html#kfigure"title="(in LinuxDoc v20181010)"><spanclass="xref std std-ref">linuxdoc</span></a> the build process
is flexible. To get best results in the generated output format, install
<aclass="reference external"href="https://www.imagemagick.org">ImageMagick</a> and <aclass="reference external"href="https://graphviz.gitlab.io">Graphviz</a>.</p>
</div>
<p>Searx’s sphinx setup includes: <aclass="reference external"href="https://return42.github.io/linuxdoc/linuxdoc-howto/kfigure.html#kfigure"title="(in LinuxDoc v20181010)"><span>Scalable figure and image handling</span></a>. Scaleable here means;
scaleable in sense of the build process. Normally in absence of a converter
tool, the build process will break. From the authors POV it’s annoying to care
about the build process when handling with images, especially since he has no
access to the build process. With <aclass="reference external"href="https://return42.github.io/linuxdoc/linuxdoc-howto/kfigure.html#kfigure"title="(in LinuxDoc v20181010)"><span>Scalable figure and image handling</span></a> the build process
continues and scales output quality in dependence of installed image processors.</p>
<p>If you want to add an image, you should use the <codeclass="docutils literal notranslate"><spanclass="pre">kernel-figure</span></code> (inheritance
of <aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure">figure</a>) and <codeclass="docutils literal notranslate"><spanclass="pre">kernel-image</span></code> (inheritance of <aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#image">image</a>)
directives. E.g. to insert a figure with a scaleable image format use SVG
To refer the figure, a caption block is needed: <spanclass="na">:ref:</span><spanclass="nv">`svg image example`</span>.
</pre></div>
</div>
<divclass="figure align-default"id="id7">
<imgalt="SVG image example"src="../_images/svg_image.svg"/><pclass="caption"><spanclass="caption-number">Fig. 2 </span><spanclass="caption-text">Simple SVG image.</span><aclass="headerlink"href="#id7"title="Permalink to this image">¶</a></p>
</div>
<p>To refer the figure, a caption block is needed: <aclass="reference internal"href="#svg-image-example"><spanclass="std std-ref">Simple SVG image.</span></a>.</p>
<divclass="section"id="dot-files-aka-graphviz">
<h3><aclass="toc-backref"href="#id30">DOT files (aka Graphviz)</a><aclass="headerlink"href="#dot-files-aka-graphviz"title="Permalink to this headline">¶</a></h3>
<p>With <aclass="reference external"href="https://return42.github.io/linuxdoc/linuxdoc-howto/kfigure.html#kernel-figure"title="(in LinuxDoc v20181010)"><span>kernel-figure & kernel-image</span></a> reST support for <strong>DOT</strong> formatted files is
<p>A simple example is shown in <aclass="reference internal"href="#dot-file-example"><spanclass="std std-ref">DOT’s hello world example</span></a>:</p>
<imgalt="hello world"src="../_images/hello.svg"/><pclass="caption"><spanclass="caption-number">Fig. 3 </span><spanclass="caption-text">DOT’s hello world example</span><aclass="headerlink"href="#id8"title="Permalink to this image">¶</a></p>
</div>
</div>
</div>
<divclass="section"id="kernel-render-dot">
<h3><aclass="toc-backref"href="#id31"><codeclass="docutils literal notranslate"><spanclass="pre">kernel-render</span></code> DOT</a><aclass="headerlink"href="#kernel-render-dot"title="Permalink to this headline">¶</a></h3>
<p>Embed <em>render</em> markups (or languages) like Graphviz’s <strong>DOT</strong> is provided by the
<aclass="reference external"href="https://return42.github.io/linuxdoc/linuxdoc-howto/kfigure.html#kernel-render"title="(in LinuxDoc v20181010)"><span>kernel-render</span></a> directive. A simple example of embedded <aclass="reference external"href="https://graphviz.gitlab.io/_pages/doc/info/lang.html">DOT</a> is
shown in figure <aclass="reference internal"href="#dot-render-example"><spanclass="std std-ref">Embedded DOT (Graphviz) code</span></a>:</p>
Attribute <spanclass="s">``caption``</span> is needed, if you want to refer the figure: :ref:`dot
render example`.
</pre></div>
</div>
<p>Please note <aclass="reference external"href="https://return42.github.io/linuxdoc/linuxdoc-howto/kfigure.html#kfigure-build-tools"title="(in LinuxDoc v20181010)"><spanclass="xref std std-ref">build tools</span></a>. If <aclass="reference external"href="https://graphviz.gitlab.io">Graphviz</a> is
installed, you will see an vector image. If not, the raw markup is inserted as
<em>literal-block</em>.</p>
<divclass="rst-example admonition">
<pclass="admonition-title">kernel-render DOT</p>
<divclass="figure align-default"id="id9">
<spanid="dot-render-example"></span><imgalt="digraph"src="../_images/DOT-57a4a7f78690d0b6b884bc59f36e84cfb0b61f76.svg"/><pclass="caption"><spanclass="caption-number">Fig. 4 </span><spanclass="caption-text">Embedded DOT (Graphviz) code</span><aclass="headerlink"href="#id9"title="Permalink to this image">¶</a></p>
</div>
<p>Attribute <codeclass="docutils literal notranslate"><spanclass="pre">caption</span></code> is needed, if you want to refer the figure: <aclass="reference internal"href="#dot-render-example"><spanclass="std std-ref">Embedded DOT (Graphviz) code</span></a>.</p>
</div>
</div>
<divclass="section"id="kernel-render-svg">
<h3><aclass="toc-backref"href="#id32"><codeclass="docutils literal notranslate"><spanclass="pre">kernel-render</span></code> SVG</a><aclass="headerlink"href="#kernel-render-svg"title="Permalink to this headline">¶</a></h3>
<p>A simple example of embedded <aclass="reference external"href="https://www.w3.org/TR/SVG11/expanded-toc.html">SVG</a> is shown in figure <aclass="reference internal"href="#svg-render-example"><spanclass="std std-ref">Embedded SVG markup</span></a>:</p>
<spanid="svg-render-example"></span><imgalt="so-nw-arrow"src="../_images/SVG-1fb7029fa2cc454a267bae271cccb2c591387416.svg"/><pclass="caption"><spanclass="caption-number">Fig. 5 </span><spanclass="caption-text">Embedded <strong>SVG</strong> markup</span><aclass="headerlink"href="#id10"title="Permalink to this image">¶</a></p>
</div>
</div>
</div>
</div>
<divclass="section"id="list-markups">
<spanid="rest-lists"></span><h2><aclass="toc-backref"href="#id33">List markups</a><aclass="headerlink"href="#list-markups"title="Permalink to this headline">¶</a></h2>
<divclass="section"id="bullet-list">
<h3><aclass="toc-backref"href="#id34">Bullet list</a><aclass="headerlink"href="#bullet-list"title="Permalink to this headline">¶</a></h3>
<p>List markup (<aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists">ref</a>) is simple:</p>
<divclass="highlight-reST notranslate"><divclass="highlight"><pre><span></span><spanclass="m">-</span> This is a bulleted list.
<spanclass="m">1.</span> Nested lists are possible, but be aware that they must be separated from
the parent list items by blank line
<spanclass="m">2.</span> Second item of nested list
<spanclass="m">-</span> It has two items, the second
item uses two lines.
<spanclass="m">#.</span> This is a numbered list.
<spanclass="m">#.</span> It has two items too.
</pre></div>
</div>
<divclass="rst-example admonition">
<pclass="admonition-title">bullet list</p>
<ulclass="simple">
<li><p>This is a bulleted list.</p>
<olclass="arabic simple">
<li><p>Nested lists are possible, but be aware that they must be separated from
the parent list items by blank line</p></li>
<li><p>Second item of nested list</p></li>
</ol>
</li>
<li><p>It has two items, the second
item uses two lines.</p></li>
</ul>
<olclass="arabic simple">
<li><p>This is a numbered list.</p></li>
<li><p>It has two items too.</p></li>
</ol>
</div>
</div>
<divclass="section"id="horizontal-list">
<h3><aclass="toc-backref"href="#id35">Horizontal list</a><aclass="headerlink"href="#horizontal-list"title="Permalink to this headline">¶</a></h3>
<p>The <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-hlist"title="(in Sphinx v4.0.0+/adad0e62b)"><codeclass="xref rst rst-dir docutils literal notranslate"><spanclass="pre">..</span><spanclass="pre">hlist::</span></code></a> transforms a bullet list into a more compact
<p>Each definition list (<aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#definition-lists">ref</a>) item contains a term,
optional classifiers and a definition. A term is a simple one-line word or
phrase. Optional classifiers may follow the term on the same line, each after
an inline ‘ : ‘ (<strong>space, colon, space</strong>). A definition is a block indented
relative to the term, and may contain multiple paragraphs and other body
elements. There may be no blank line between a term line and a definition block
(<em>this distinguishes definition lists from block quotes</em>). Blank lines are
required before the first and after the last definition list item, but are
optional in-between.</p>
<p>Definition lists are created as follows:</p>
<divclass="highlight-reST notranslate"><divclass="highlight"><pre><span></span>term 1 (up to a line of text)
Definition 1.
See the typo : this line is not a term!
And this is not term's definition. <spanclass="gs">**There is a blank line**</span> in between
the line above and this paragraph. That's why this paragraph is taken as
<spanclass="gs">**block quote**</span> (<spanclass="na">:duref:</span><spanclass="nv">`ref <block-quotes>`</span>) and not as term's definition!
term 2
Definition 2, paragraph 1.
Definition 2, paragraph 2.
term 3 : classifier
Definition 3.
term 4 : classifier one : classifier two
Definition 4.
</pre></div>
</div>
<divclass="rst-example admonition">
<pclass="admonition-title">definition list</p>
<dlclass="simple">
<dt>term 1 (up to a line of text)</dt><dd><p>Definition 1.</p>
</dd>
</dl>
<p>See the typo : this line is not a term!</p>
<blockquote>
<div><p>And this is not term’s definition. <strong>There is a blank line</strong> in between
the line above and this paragraph. That’s why this paragraph is taken as
<strong>block quote</strong> (<aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#block-quotes">ref</a>) and not as term’s definition!</p>
<h3><aclass="toc-backref"href="#id37">Quoted paragraphs</a><aclass="headerlink"href="#quoted-paragraphs"title="Permalink to this headline">¶</a></h3>
<p>Quoted paragraphs (<aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#block-quotes">ref</a>) are created by just indenting
them more than the surrounding paragraphs. Line blocks (<aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#line-blocks">ref</a>) are a way of preserving line breaks:</p>
<pclass="admonition-title">Quoted paragraph and line block</p>
<p>normal paragraph …
lorem ipsum.</p>
<blockquote>
<div><p>Quoted paragraph …
lorem ipsum.</p>
</div></blockquote>
<divclass="line-block">
<divclass="line">These lines are</div>
<divclass="line">broken exactly like in</div>
<divclass="line">the source file.</div>
</div>
</div>
</div>
<divclass="section"id="field-lists">
<spanid="rest-field-list"></span><h3><aclass="toc-backref"href="#id38">Field Lists</a><aclass="headerlink"href="#field-lists"title="Permalink to this headline">¶</a></h3>
<divclass="sidebar">
<pclass="sidebar-title">bibliographic fields</p>
<p>First lines fields are bibliographic fields, see <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html">Sphinx Field Lists</a>.</p>
</div>
<p>Field lists are used as part of an extension syntax, such as options for
directives, or database-like records meant for further processing. Field lists
are mappings from field names to field bodies. They marked up like this:</p>
<spanclass="sd">"""A function just for me.</span>
<spanclass="sd"> :param my_arg: The first of my arguments.</span>
<spanclass="sd"> :param my_other_arg: The second of my arguments.</span>
<spanclass="sd"> :returns: A message (just for me, of course).</span>
<spanclass="sd">"""</span>
</pre></div>
</div>
</div>
<divclass="section"id="further-list-blocks">
<h3><aclass="toc-backref"href="#id39">Further list blocks</a><aclass="headerlink"href="#further-list-blocks"title="Permalink to this headline">¶</a></h3>
<ulclass="simple">
<li><p>field lists (<aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists">ref</a>, with caveats noted in
<h2><aclass="toc-backref"href="#id40">Admonitions</a><aclass="headerlink"href="#admonitions"title="Permalink to this headline">¶</a></h2>
<divclass="section"id="sidebar">
<h3><aclass="toc-backref"href="#id41">Sidebar</a><aclass="headerlink"href="#sidebar"title="Permalink to this headline">¶</a></h3>
<p>Sidebar is an eye catcher, often used for admonitions pointing further stuff or
site effects. Here is the source of the sidebar <aclass="reference internal"href="#rest-primer"><spanclass="std std-ref">on top of this page</span></a>.</p>
<divclass="highlight-reST notranslate"><divclass="highlight"><pre><span></span><spanclass="p">..</span><spanclass="ow">sidebar</span><spanclass="p">::</span> KISS_ and readability_
Instead of defining more and more roles, we at searx encourage our
contributors to follow principles like KISS_ and readability_.
</pre></div>
</div>
</div>
<divclass="section"id="generic-admonition">
<h3><aclass="toc-backref"href="#id42">Generic admonition</a><aclass="headerlink"href="#generic-admonition"title="Permalink to this headline">¶</a></h3>
<p>The generic <aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions">admonition</a> needs a title:</p>
<divclass="highlight-reST notranslate"><divclass="highlight"><pre><span></span><spanclass="p">..</span><spanclass="ow">admonition</span><spanclass="p">::</span> generic admonition title
<h3><aclass="toc-backref"href="#id43">Specific admonitions</a><aclass="headerlink"href="#specific-admonitions"title="Permalink to this headline">¶</a></h3>
<spanid="rest-simple-table"></span><h3><aclass="toc-backref"href="#id45">Simple tables</a><aclass="headerlink"href="#simple-tables"title="Permalink to this headline">¶</a></h3>
<p><aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#simple-tables">Simple tables</a> allow <em>colspan</em> but not <em>rowspan</em>. If
your table need some metadata (e.g. a title) you need to add the <codeclass="docutils literal notranslate"><spanclass="pre">..</span><spanclass="pre">table::</span>
<spanclass="pre">directive</span></code><aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#table">(ref)</a> in front and place the table in its body:</p>
<divclass="highlight-reST notranslate"><divclass="highlight"><pre><span></span><spanclass="p">..</span><spanclass="ow">table</span><spanclass="p">::</span> foo gate truth table
<caption><spanclass="caption-number">Table 6 </span><spanclass="caption-text">foo gate truth table</span><aclass="headerlink"href="#id11"title="Permalink to this table">¶</a></caption>
<spanid="rest-grid-table"></span><h3><aclass="toc-backref"href="#id46">Grid tables</a><aclass="headerlink"href="#grid-tables"title="Permalink to this headline">¶</a></h3>
<p><aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables">Grid tables</a> allow colspan <em>colspan</em> and <em>rowspan</em>:</p>
<divclass="highlight-reST notranslate"><divclass="highlight"><pre><span></span><spanclass="p">..</span><spanclass="ow">table</span><spanclass="p">::</span> grid table example
<caption><spanclass="caption-number">Table 7 </span><spanclass="caption-text">grid table example</span><aclass="headerlink"href="#id12"title="Permalink to this table">¶</a></caption>
<tdcolspan="2"><p>Cells may span columns.</p></td>
</tr>
<trclass="row-even"><td><p>body row 3</p></td>
<tdrowspan="2"><p>Cells may
span rows.</p></td>
<tdrowspan="2"><ulclass="simple">
<li><p>Cells</p></li>
<li><p>contain</p></li>
<li><p>blocks.</p></li>
</ul>
</td>
</tr>
<trclass="row-odd"><td><p>body row 4</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<divclass="section"id="flat-table">
<spanid="rest-flat-table"></span><h3><aclass="toc-backref"href="#id47">flat-table</a><aclass="headerlink"href="#flat-table"title="Permalink to this headline">¶</a></h3>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">flat-table</span></code> is a further developed variant of the <aclass="reference external"href="https://return42.github.io/linuxdoc/linuxdoc-howto/table-markup.html#list-table-directives"title="(in LinuxDoc v20181010)"><spanclass="xref std std-ref">list tables</span></a>. It is a double-stage list similar to the
<aclass="reference external"href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#list-table">list-table</a> with some additional features:</p>
<dlclass="simple">
<dt>column-span: <codeclass="docutils literal notranslate"><spanclass="pre">cspan</span></code></dt><dd><p>with the role <codeclass="docutils literal notranslate"><spanclass="pre">cspan</span></code> a cell can be extended through additional columns</p>
</dd>
<dt>row-span: <codeclass="docutils literal notranslate"><spanclass="pre">rspan</span></code></dt><dd><p>with the role <codeclass="docutils literal notranslate"><spanclass="pre">rspan</span></code> a cell can be extended through additional rows</p>
</dd>
<dt>auto-span:</dt><dd><p>spans rightmost cell of a table row over the missing cells on the right side
of that table-row. With Option <codeclass="docutils literal notranslate"><spanclass="pre">:fill-cells:</span></code> this behavior can changed
from <em>auto span</em> to <em>auto fill</em>, which automatically inserts (empty) cells
<p>The example below shows how to use this markup. The first level of the staged
list is the <em>table-row</em>. In the <em>table-row</em> there is only one markup allowed,
the list of the cells in this <em>table-row</em>. Exception are <em>comments</em> ( <codeclass="docutils literal notranslate"><spanclass="pre">..</span></code> )
and <em>targets</em> (e.g. a ref to <aclass="reference internal"href="#row-body-2"><spanclass="std std-ref">row 2 of table’s body</span></a>).</p>
<divclass="highlight-reST notranslate"><divclass="highlight"><pre><span></span><spanclass="p">..</span><spanclass="ow">flat-table</span><spanclass="p">::</span><spanclass="s">``flat-table``</span> example
<caption><spanclass="caption-number">Table 8 </span><spanclass="caption-text"><codeclass="docutils literal notranslate"><spanclass="pre">flat-table</span></code> example</span><aclass="headerlink"href="#id13"title="Permalink to this table">¶</a></caption>
<h3><aclass="toc-backref"href="#id48">CSV table</a><aclass="headerlink"href="#csv-table"title="Permalink to this headline">¶</a></h3>
<p>CSV table might be the choice if you want to include CSV-data from a outstanding
(build) process into your documentation.</p>
<divclass="highlight-reST notranslate"><divclass="highlight"><pre><span></span><spanclass="p">..</span><spanclass="ow">csv-table</span><spanclass="p">::</span> CSV table example
<p>Content of file <codeclass="docutils literal notranslate"><spanclass="pre">csv_table.txt</span></code>:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>stub col row 1, column, "loremLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
voluptua."
stub col row 1, "At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.", column
<caption><spanclass="caption-number">Table 9 </span><spanclass="caption-text">CSV table example</span><aclass="headerlink"href="#id14"title="Permalink to this table">¶</a></caption>
<trclass="row-even"><thclass="stub"><p>stub col row 1</p></th>
<td><p>column</p></td>
<td><p>loremLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
voluptua.</p></td>
</tr>
<trclass="row-odd"><thclass="stub"><p>stub col row 1</p></th>
<td><p>At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.</p></td>
<td><p>column</p></td>
</tr>
<trclass="row-even"><thclass="stub"><p>stub col row 1</p></th>
<td><p>column</p></td>
<td><p>column</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<divclass="section"id="templating">
<h2><aclass="toc-backref"href="#id49">Templating</a><aclass="headerlink"href="#templating"title="Permalink to this headline">¶</a></h2>
<divclass="sidebar">
<pclass="sidebar-title">Build environment</p>
<p>All <em>generic-doc</em> tasks are running in the <aclass="reference internal"href="makefile.html#make-pyenv"><spanclass="std std-ref">build environment</span></a>.</p>
</div>
<p>Templating is suitable for documentation which is created generic at the build
time. The <aclass="reference external"href="https://github.com/tardyp/sphinx-jinja">sphinx-jinja</a> extension evaluates <aclass="reference external"href="https://jinja.palletsprojects.com/">jinja</a> templates in the <aclass="reference internal"href="makefile.html#make-pyenv"><spanclass="std std-ref">build
environment</span></a> (with searx modules installed). We use this e.g. to
build chapter: <aclass="reference internal"href="../admin/engines.html#engines-generic"><spanclass="std std-ref">Engines</span></a>. Below the jinja directive from the
<aclass="reference external"href="https://github.com/return42/searx/blob/filtron/docs/admin/engines.rst">git://docs/admin/engines.rst</a> is shown:</p>
<p>The context for the template is selected in the line <codeclass="docutils literal notranslate"><spanclass="pre">..</span><spanclass="pre">jinja::</span><spanclass="pre">webapp</span></code>. In
<h2><aclass="toc-backref"href="#id50">Tabbed views</a><aclass="headerlink"href="#tabbed-views"title="Permalink to this headline">¶</a></h2>
<p>With <aclass="reference external"href="https://github.com/djungelorm/sphinx-tabs">sphinx-tabs</a> extension we have <em>tabbed views</em>. To provide installation
instructions with one tab per distribution we use the <aclass="reference external"href="https://github.com/djungelorm/sphinx-tabs#group-tabs">group-tabs</a> directive,
others are <aclass="reference external"href="https://github.com/djungelorm/sphinx-tabs#basic-tabs">basic-tabs</a> and <aclass="reference external"href="https://github.com/djungelorm/sphinx-tabs#code-tabs">code-tabs</a>. Below a <em>group-tab</em> example from
<aclass="reference internal"href="../admin/buildhosts.html#docs-build"><spanclass="std std-ref">Build docs</span></a> is shown:</p>
<spanid="math"></span><h2><aclass="toc-backref"href="#id51">Math equations</a><aclass="headerlink"href="#math-equations"title="Permalink to this headline">¶</a></h2>
<divclass="sidebar">
<pclass="sidebar-title">About LaTeX</p>
<ulclass="simple">
<li><p><aclass="reference external"href="http://vesta.informatik.rwth-aachen.de/ftp/pub/mirror/ctan/macros/latex/required/amsmath/amsldoc.pdf">amsmath user guide</a></p></li>
<p>To embed LaTeX markup in reST documents, use role <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-math"title="(in Sphinx v4.0.0+/adad0e62b)"><codeclass="xref rst rst-role docutils literal notranslate"><spanclass="pre">:math:</span></code></a> for
inline and directive <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-math"title="(in Sphinx v4.0.0+/adad0e62b)"><codeclass="xref rst rst-dir docutils literal notranslate"><spanclass="pre">..</span><spanclass="pre">math::</span></code></a> for block markup.</p>
<p><spanclass="eqno">(1)<aclass="headerlink"href="#equation-schroedinger-general"title="Permalink to this equation">¶</a></span><imgsrc="../_images/math/a6a994cb6e7278ec30eaebe7e636046d3deccb5b.svg"alt="\mathrm{i}\hbar\dfrac{\partial}{\partialt}|\,\psi(t)\rangle =
<p>The next example shows the difference of <codeclass="docutils literal notranslate"><spanclass="pre">\tfrac</span></code> (<em>textstyle</em>) and <codeclass="docutils literal notranslate"><spanclass="pre">\dfrac</span></code>
(<em>displaystyle</em>) used in a inline markup or another fraction.</p>
