This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<spanid="id1"></span><h1>reST primer<aclass="headerlink"href="#rest-primer"title="Link to this heading">¶</a></h1>
<asideclass="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 SearXNG 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>
</aside>
<p>We at SearXNG 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="https://www.sphinx-doc.org">Sphinx</a> project a HTML output is
generated and deployed at <aclass="reference external"href="https://docs.searxng.org/">docs.searxng.org</a>. For build prerequisites read
<p>The source files of SearXNG’s documentation are located at <aclass="extlink-origin reference external"href="https://github.com/searxng/searxng/blob/master/docs">git://docs</a>.
Sphinx assumes source files to be encoded in UTF-8 by default. 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="https://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>
<asideclass="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>
</aside>
<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>
<sectionid="soft-skills">
<h2><aclass="toc-backref"href="#id15"role="doc-backlink">Soft skills</a><aclass="headerlink"href="#soft-skills"title="Link to this heading">¶</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>
</ul>
<p>To be more concrete what a <em>point of view</em> means. In the (<aclass="extlink-origin reference external"href="https://github.com/searxng/searxng/blob/master/docs">git://docs</a>)
folder we have three sections (and the <em>blog</em> folder), each dedicate to a
different group of audience.</p>
<dlclass="simple">
<dt>User’s POV: <aclass="extlink-origin reference external"href="https://github.com/searxng/searxng/blob/master/docs/user">git://docs/user</a></dt><dd><p>A typical user knows about search engines and might have heard about
meta crawlers and privacy.</p>
</dd>
<dt>Admin’s POV: <aclass="extlink-origin reference external"href="https://github.com/searxng/searxng/blob/master/docs/admin">git://docs/admin</a></dt><dd><p>A typical Admin knows about setting up services on a linux system, but he does
not know all the pros and cons of a SearXNG setup.</p>
</dd>
<dt>Developer’s POV: <aclass="extlink-origin reference external"href="https://github.com/searxng/searxng/blob/master/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>
</section>
<sectionid="basic-inline-markup">
<spanid="rest-inline-markup"></span><h2><aclass="toc-backref"href="#id16"role="doc-backlink">Basic inline markup</a><aclass="headerlink"href="#basic-inline-markup"title="Link to this heading">¶</a></h2>
<p>Basic inline markup is done with asterisks and backquotes. If asterisks or
backquotes appear in running text and could be confused with inline markup
delimiters, they have to be escaped with a backslash (<codeclass="docutils literal notranslate"><spanclass="pre">\*pointer</span></code>).</p>
<tableclass="docutils align-default"id="id4">
<caption><spanclass="caption-number">Table 9 </span><spanclass="caption-text">basic inline markup</span><aclass="headerlink"href="#id4"title="Link to this table">¶</a></caption>
<spanid="rest-basic-structure"></span><h2><aclass="toc-backref"href="#id17"role="doc-backlink">Basic article structure</a><aclass="headerlink"href="#basic-article-structure"title="Link to this heading">¶</a></h2>
<p>The basic structure of an article makes use of heading adornments to markup
chapter, sections and subsections.</p>
<sectionid="rest-template">
<spanid="id2"></span><h3><aclass="toc-backref"href="#id18"role="doc-backlink">reST template</a><aclass="headerlink"href="#rest-template"title="Link to this heading">¶</a></h3>
<h2><aclass="toc-backref"href="#id20"role="doc-backlink">Anchors & Links</a><aclass="headerlink"href="#anchors-links"title="Link to this heading">¶</a></h2>
<sectionid="anchors">
<spanid="rest-anchor"></span><h3><aclass="toc-backref"href="#id21"role="doc-backlink">Anchors</a><aclass="headerlink"href="#anchors"title="Link to this heading">¶</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 manually :ref:`foo
<p>Visit chapter <aclass="reference internal"href="#rest-anchor"><spanclass="std std-ref">Anchors</span></a>. Or set hyperlink text manually <aclass="reference internal"href="#rest-anchor"><spanclass="std std-ref">foo
bar</span></a>.</p>
</div>
</section>
<sectionid="link-ordinary-url">
<spanid="rest-ordinary-ref"></span><h3><aclass="toc-backref"href="#id22"role="doc-backlink">Link ordinary URL</a><aclass="headerlink"href="#link-ordinary-url"title="Link to this heading">¶</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>
</section>
<sectionid="smart-refs">
<spanid="rest-smart-ref"></span><h3><aclass="toc-backref"href="#id23"role="doc-backlink">Smart refs</a><aclass="headerlink"href="#smart-refs"title="Link to this heading">¶</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="https://www.sphinx-doc.org/en/stable/ext/intersphinx.html">intersphinx</a> referencing external
content becomes smart.</p>
<tableclass="docutils align-default"id="id5">
<caption><spanclass="caption-number">Table 10 </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="https://www.sphinx-doc.org/en/stable/ext/intersphinx.html">intersphinx</a></span><aclass="headerlink"href="#id5"title="Link to this table">¶</a></caption>
<p>Intersphinx is configured in <aclass="extlink-origin reference external"href="https://github.com/searxng/searxng/blob/master/docs/conf.py">git://docs/conf.py</a>:</p>
<h2><aclass="toc-backref"href="#id24"role="doc-backlink">Literal blocks</a><aclass="headerlink"href="#literal-blocks"title="Link to this heading">¶</a></h2>
<p>The simplest form of <aclass="extlink-duref reference external"href="https://docutils.sourceforge.io/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="extlink-dudir reference external"href="https://docutils.sourceforge.io/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 (latter one expands environment variables in the path name).</p>
<sectionid="rest-literal">
<spanid="id3"></span><h3><aclass="toc-backref"href="#id25"role="doc-backlink"><codeclass="docutils literal notranslate"><spanclass="pre">::</span></code></a><aclass="headerlink"href="#rest-literal"title="Link to this heading">¶</a></h3>
<spanid="rest-code"></span><h3><aclass="toc-backref"href="#id26"role="doc-backlink"><codeclass="docutils literal notranslate"><spanclass="pre">code-block</span></code></a><aclass="headerlink"href="#code-block"title="Link to this heading">¶</a></h3>
<asideclass="sidebar">
<pclass="sidebar-title">Syntax highlighting</p>
<p>is handled by <aclass="reference external"href="https://pygments.org/languages/">pygments</a>.</p>
</aside>
<p>The <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block"title="(in Sphinx v8.2.0)"><codeclass="xref rst rst-dir docutils literal notranslate"><spanclass="pre">code-block</span></code></a> directive is a variant of the <aclass="extlink-dudir reference external"href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#code">code</a> directive
with additional options. To learn more about code literals visit
<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="Link to this code">¶</a></div>
<h2><aclass="toc-backref"href="#id27"role="doc-backlink">Unicode substitution</a><aclass="headerlink"href="#unicode-substitution"title="Link to this heading">¶</a></h2>
<spanid="rest-roles"></span><h2><aclass="toc-backref"href="#id28"role="doc-backlink">Roles</a><aclass="headerlink"href="#roles"title="Link to this heading">¶</a></h2>
<p>A <em>custom interpreted text role</em> (<aclass="extlink-duref reference external"href="https://docutils.sourceforge.io/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
<spanclass="na">:rolename:</span><spanclass="nv">`ref text <ref-name>`</span>
</pre></div>
</div>
<tableclass="docutils align-default"id="id6">
<caption><spanclass="caption-number">Table 11 </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="https://www.sphinx-doc.org/en/stable/ext/intersphinx.html">intersphinx</a></span><aclass="headerlink"href="#id6"title="Link to this table">¶</a></caption>
<h2><aclass="toc-backref"href="#id29"role="doc-backlink">Figures & Images</a><aclass="headerlink"href="#figures-images"title="Link to this heading">¶</a></h2>
<asideclass="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 v20240509)"><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>
</aside>
<p>SearXNG’s sphinx setup includes: <aclass="reference external"href="https://return42.github.io/linuxdoc/linuxdoc-howto/kfigure.html#kfigure"title="(in LinuxDoc v20240509)"><span>Scalable figure and image handling</span></a>. Scalable here means;
scalable 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 v20240509)"><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="extlink-dudir reference external"href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure">figure</a>) and <codeclass="docutils literal notranslate"><spanclass="pre">kernel-image</span></code> (inheritance of <aclass="extlink-dudir reference external"href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#image">image</a>)
directives. E.g. to insert a figure with a scalable image format use SVG
<p><spanclass="caption-number">Fig. 4 </span><spanclass="caption-text">Simple SVG image.</span><aclass="headerlink"href="#id7"title="Link to this image">¶</a></p>
</figcaption>
</figure>
<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>
<sectionid="dot-files-aka-graphviz">
<h3><aclass="toc-backref"href="#id30"role="doc-backlink">DOT files (aka Graphviz)</a><aclass="headerlink"href="#dot-files-aka-graphviz"title="Link to this heading">¶</a></h3>
<p>With <aclass="reference external"href="https://return42.github.io/linuxdoc/linuxdoc-howto/kfigure.html#kernel-figure"title="(in LinuxDoc v20240509)"><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>
<p><spanclass="caption-number">Fig. 5 </span><spanclass="caption-text">DOT’s hello world example</span><aclass="headerlink"href="#id8"title="Link to this image">¶</a></p>
</figcaption>
</figure>
</div>
</section>
<sectionid="kernel-render-dot">
<h3><aclass="toc-backref"href="#id31"role="doc-backlink"><codeclass="docutils literal notranslate"><spanclass="pre">kernel-render</span></code> DOT</a><aclass="headerlink"href="#kernel-render-dot"title="Link to this heading">¶</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 v20240509)"><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>
<p><spanclass="caption-number">Fig. 6 </span><spanclass="caption-text">Embedded DOT (Graphviz) code</span><aclass="headerlink"href="#id9"title="Link to this image">¶</a></p>
</figcaption>
</figure>
<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>
</section>
<sectionid="kernel-render-svg">
<h3><aclass="toc-backref"href="#id32"role="doc-backlink"><codeclass="docutils literal notranslate"><spanclass="pre">kernel-render</span></code> SVG</a><aclass="headerlink"href="#kernel-render-svg"title="Link to this heading">¶</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>
<p><spanclass="caption-number">Fig. 7 </span><spanclass="caption-text">Embedded <strong>SVG</strong> markup</span><aclass="headerlink"href="#id10"title="Link to this image">¶</a></p>
</figcaption>
</figure>
</div>
</section>
</section>
<sectionid="list-markups">
<spanid="rest-lists"></span><h2><aclass="toc-backref"href="#id33"role="doc-backlink">List markups</a><aclass="headerlink"href="#list-markups"title="Link to this heading">¶</a></h2>
<sectionid="bullet-list">
<h3><aclass="toc-backref"href="#id34"role="doc-backlink">Bullet list</a><aclass="headerlink"href="#bullet-list"title="Link to this heading">¶</a></h3>
<p>List markup (<aclass="extlink-duref reference external"href="https://docutils.sourceforge.io/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>
</section>
<sectionid="horizontal-list">
<h3><aclass="toc-backref"href="#id35"role="doc-backlink">Horizontal list</a><aclass="headerlink"href="#horizontal-list"title="Link to this heading">¶</a></h3>
<p>The <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-hlist"title="(in Sphinx v8.2.0)"><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
<h3><aclass="toc-backref"href="#id36"role="doc-backlink">Definition list</a><aclass="headerlink"href="#definition-list"title="Link to this heading">¶</a></h3>
<asideclass="sidebar">
<pclass="sidebar-title">Note ..</p>
<ulclass="simple">
<li><p>the term cannot have more than one line of text</p></li>
<li><p>there is <strong>no blank line between term and definition block</strong> // this
distinguishes definition lists (<aclass="extlink-duref reference external"href="https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists">ref</a>) from block
<p>Each definition list (<aclass="extlink-duref reference external"href="https://docutils.sourceforge.io/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="extlink-duref reference external"href="https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#block-quotes">ref</a>) and not as term’s definition!</p>
<h3><aclass="toc-backref"href="#id37"role="doc-backlink">Quoted paragraphs</a><aclass="headerlink"href="#quoted-paragraphs"title="Link to this heading">¶</a></h3>
<p>Quoted paragraphs (<aclass="extlink-duref reference external"href="https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#block-quotes">ref</a>) are created by just indenting
them more than the surrounding paragraphs. Line blocks (<aclass="extlink-duref reference external"href="https://docutils.sourceforge.io/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>
</section>
<sectionid="field-lists">
<spanid="rest-field-list"></span><h3><aclass="toc-backref"href="#id38"role="doc-backlink">Field Lists</a><aclass="headerlink"href="#field-lists"title="Link to this heading">¶</a></h3>
<asideclass="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>
</aside>
<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>
<divclass="highlight-reST notranslate"><divclass="highlight"><pre><span></span><spanclass="nc">:fieldname:</span> Field content
<spanclass="nc">:foo:</span> first paragraph in field foo
<spanclass="w"></span><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>
</section>
<sectionid="further-list-blocks">
<h3><aclass="toc-backref"href="#id39"role="doc-backlink">Further list blocks</a><aclass="headerlink"href="#further-list-blocks"title="Link to this heading">¶</a></h3>
<ulclass="simple">
<li><p>field lists (<aclass="extlink-duref reference external"href="https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists">ref</a>, with caveats noted in
<h2><aclass="toc-backref"href="#id40"role="doc-backlink">Admonitions</a><aclass="headerlink"href="#admonitions"title="Link to this heading">¶</a></h2>
<sectionid="sidebar">
<h3><aclass="toc-backref"href="#id41"role="doc-backlink">Sidebar</a><aclass="headerlink"href="#sidebar"title="Link to this heading">¶</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 SearXNG encourage our
contributors to follow principles like KISS_ and readability_.
</pre></div>
</div>
</section>
<sectionid="generic-admonition">
<h3><aclass="toc-backref"href="#id42"role="doc-backlink">Generic admonition</a><aclass="headerlink"href="#generic-admonition"title="Link to this heading">¶</a></h3>
<p>The generic <aclass="extlink-dudir reference external"href="https://docutils.sourceforge.io/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"role="doc-backlink">Specific admonitions</a><aclass="headerlink"href="#specific-admonitions"title="Link to this heading">¶</a></h3>
<spanid="rest-simple-table"></span><h3><aclass="toc-backref"href="#id45"role="doc-backlink">Simple tables</a><aclass="headerlink"href="#simple-tables"title="Link to this heading">¶</a></h3>
<p><aclass="extlink-duref reference external"href="https://docutils.sourceforge.io/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="extlink-dudir reference external"href="https://docutils.sourceforge.io/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
<spanclass="nc">:widths:</span> grid
<spanclass="nc">:align:</span> left
====== ====== ======
Inputs Output
------------- ------
A B A or B
====== ====== ======
False
--------------------
True
--------------------
True False True
(foo)
------ ------ ------
False True
(foo)
====== =============
</pre></div>
</div>
<divclass="rst-example admonition">
<pclass="admonition-title">Simple ASCII table</p>
<tableclass="docutils align-left"id="id11">
<caption><spanclass="caption-number">Table 12 </span><spanclass="caption-text">foo gate truth table</span><aclass="headerlink"href="#id11"title="Link to this table">¶</a></caption>
<spanid="rest-grid-table"></span><h3><aclass="toc-backref"href="#id46"role="doc-backlink">Grid tables</a><aclass="headerlink"href="#grid-tables"title="Link to this heading">¶</a></h3>
<p><aclass="extlink-duref reference external"href="https://docutils.sourceforge.io/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
<spanclass="o">|</span> body row 2 | Cells may span columns.|
+------------+------------+-----------+
<spanclass="o">|</span> body row 3 | Cells may | - Cells |
+------------+ span rows. | - contain |
<spanclass="o">|</span> body row 4 | | - blocks. |
+------------+------------+-----------+
</pre></div>
</div>
<divclass="rst-example admonition">
<pclass="admonition-title">ASCII grid table</p>
<tableclass="docutils align-default"id="id12">
<caption><spanclass="caption-number">Table 13 </span><spanclass="caption-text">grid table example</span><aclass="headerlink"href="#id12"title="Link 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>
</section>
<sectionid="flat-table">
<spanid="rest-flat-table"></span><h3><aclass="toc-backref"href="#id47"role="doc-backlink">flat-table</a><aclass="headerlink"href="#flat-table"title="Link to this heading">¶</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 v20240509)"><spanclass="xref std std-ref">list tables</span></a>. It is a double-stage list similar to the
<aclass="extlink-dudir reference external"href="https://docutils.sourceforge.io/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
<spanclass="nc">:header-rows:</span> 2
<spanclass="nc">:stub-columns:</span> 1
<spanclass="nc">:widths:</span> 1 1 1 1 2
<spanclass="m">*</span> - <spanclass="na">:rspan:</span><spanclass="nv">`1`</span> head / stub
<spanclass="m">-</span><spanclass="na">:cspan:</span><spanclass="nv">`3`</span> head 1.1-4
<spanclass="m">*</span> - head 2.1
<spanclass="m">-</span> head 2.2
<spanclass="m">-</span> head 2.3
<spanclass="m">-</span> head 2.4
<spanclass="m">*</span> .. row body 1 / this is a comment
<spanclass="m">-</span> cell 5.1 with automatic span to right end
<spanclass="m">*</span> - row 6
<spanclass="m">-</span> cell 6.1
<spanclass="m">-</span> ..
</pre></div>
</div>
<divclass="rst-example admonition">
<pclass="admonition-title">List table</p>
<tableclass="docutils align-default"id="id13">
<caption><spanclass="caption-number">Table 14 </span><spanclass="caption-text"><codeclass="docutils literal notranslate"><spanclass="pre">flat-table</span></code> example</span><aclass="headerlink"href="#id13"title="Link to this table">¶</a></caption>
<colgroup>
<colstyle="width: 16.7%"/>
<colstyle="width: 16.7%"/>
<colstyle="width: 16.7%"/>
<colstyle="width: 16.7%"/>
<colstyle="width: 33.3%"/>
</colgroup>
<thead>
<trclass="row-odd"><thclass="head stub"rowspan="2"><p> head / stub</p></th>
<thclass="head"colspan="4"><p> head 1.1-4</p></th>
<h3><aclass="toc-backref"href="#id48"role="doc-backlink">CSV table</a><aclass="headerlink"href="#csv-table"title="Link to this heading">¶</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-default notranslate"><divclass="highlight"><pre><span></span><spanclass="n">stub</span><spanclass="n">col</span><spanclass="n">row</span><spanclass="mi">1</span><spanclass="p">,</span><spanclass="n">column</span><spanclass="p">,</span><spanclass="s2">"loremLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy</span>
<spanclass="n">stub</span><spanclass="n">col</span><spanclass="n">row</span><spanclass="mi">1</span><spanclass="p">,</span><spanclass="s2">"At vero eos et accusam et justo duo dolores et ea rebum. Stet clita</span>
<caption><spanclass="caption-number">Table 15 </span><spanclass="caption-text">CSV table example</span><aclass="headerlink"href="#id14"title="Link to this table">¶</a></caption>
<colgroup>
<colstyle="width: 23.1%"/>
<colstyle="width: 38.5%"/>
<colstyle="width: 38.5%"/>
</colgroup>
<thead>
<trclass="row-odd"><thclass="head stub"></th>
<thclass="head"><p>Column 1</p></th>
<thclass="head"><p>Column 2</p></th>
</tr>
</thead>
<tbody>
<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>
</section>
</section>
<sectionid="templating">
<h2><aclass="toc-backref"href="#id49"role="doc-backlink">Templating</a><aclass="headerlink"href="#templating"title="Link to this heading">¶</a></h2>
<asideclass="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-install"><spanclass="std std-ref">Python environment (make install)</span></a>.</p>
</aside>
<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-install"><spanclass="std std-ref">Python environment (make install)</span></a> (with SearXNG modules installed). We use this e.g. to build chapter:
<aclass="reference internal"href="../user/configured_engines.html#configured-engines"><spanclass="std std-ref">Configured Engines</span></a>. Below the jinja directive from the
<aclass="extlink-origin reference external"href="https://github.com/searxng/searxng/blob/master/docs/admin/engines.rst">git://docs/admin/engines.rst</a> is shown:</p>
<spanclass="s"> - {{(mod.disabled and "y") or ""}}</span>
<spanclass="s"> - {{mod.timeout}}</span>
<spanclass="s"> - {{mod.weight or 1 }}</span>
<spanclass="s"> {% if mod.engine_type == 'online' %}</span>
<spanclass="s"> - {{(mod.paging and "y") or ""}}</span>
<spanclass="s"> - {{(mod.language_support and "y") or ""}}</span>
<spanclass="s"> - {{(mod.safesearch and "y") or ""}}</span>
<spanclass="s"> - {{(mod.time_range_support and "y") or ""}}</span>
<spanclass="s"> {% else %}</span>
<spanclass="s"> - :cspan:`3` not applicable ({{mod.engine_type}})</span>
<spanclass="s"> {% endif %}</span>
<spanclass="s"> {% endfor %}</span>
<spanclass="s"> {% endfor %}</span>
<spanclass="s"> {% endfor %}</span>
</pre></div>
</div>
<p>The context for the template is selected in the line <codeclass="docutils literal notranslate"><spanclass="pre">..</span><spanclass="pre">jinja::</span><spanclass="pre">searx</span></code>. In
contains the <codeclass="docutils literal notranslate"><spanclass="pre">engines</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">plugins</span></code>.</p>
<h2><aclass="toc-backref"href="#id50"role="doc-backlink">Tabbed views</a><aclass="headerlink"href="#tabbed-views"title="Link to this heading">¶</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>
<spanclass="p"> ..</span><spanclass="ow">code-block</span><spanclass="p">::</span> sh
$ sudo dnf install ShellCheck
</pre></div>
</div>
</section>
<sectionid="math-equations">
<spanid="math"></span><h2><aclass="toc-backref"href="#id51"role="doc-backlink">Math equations</a><aclass="headerlink"href="#math-equations"title="Link to this heading">¶</a></h2>
<asideclass="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>The input language for mathematics is LaTeX markup using the <aclass="extlink-ctan reference external"href="https://ctan.org/pkg/amsmath">CTAN: amsmath</a>
package.</p>
<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 v8.2.0)"><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 v8.2.0)"><codeclass="xref rst rst-dir docutils literal notranslate"><spanclass="pre">..</span><spanclass="pre">math::</span></code></a> for block markup.</p>
<divclass="highlight-reST notranslate"><divclass="highlight"><pre><span></span>In <spanclass="na">:math:numref:</span><spanclass="nv">`schroedinger general`</span> the time-dependent Schrödinger equation
<p><spanclass="eqno">(1)<aclass="headerlink"href="#equation-schroedinger-general"title="Link to this equation">¶</a></span><imgsrc="../_images/math/a6a994cb6e7278ec30eaebe7e636046d3deccb5b.svg"alt="\mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
\hat{H} |\,\psi (t) \rangle."/></p>
</div></div>
<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>