searx/dev/reST.html

1616 lines
99 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

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.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>reST primer &#8212; Searx Documentation (Searx-1.0.0.tex)</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../_static/searx.css" />
<link rel="stylesheet" type="text/css" href="../_static/tabs.css" />
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Tooling box searx_extra for developers and users" href="../searx_extra/index.html" />
<link rel="prev" title="Makefile" href="makefile.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="../searx_extra/index.html" title="Tooling box searx_extra for developers and users"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="makefile.html" title="Makefile"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Searx Documentation (Searx-1.0.0.tex)</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Developer documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">reST primer</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="rest-primer">
<span id="id1"></span><h1>reST primer<a class="headerlink" href="#rest-primer" title="Permalink to this headline"></a></h1>
<div class="sidebar">
<p class="sidebar-title"><a class="reference external" href="https://en.wikipedia.org/wiki/KISS_principle">KISS</a> and <a class="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 <a class="reference external" href="https://en.wikipedia.org/wiki/KISS_principle">KISS</a> and <a class="reference external" href="https://docs.python-guide.org/writing/style/">readability</a>.</p>
</div>
<p>We at searx are using reStructuredText (aka <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reST</a>) markup for all kind of
documentation, with the builders from the <a class="reference external" href="https://www.sphinx-doc.org">Sphinx</a> project a HTML output is
generated and deployed at <a class="reference external" href="https://searx.github.io/searx/.">github.io</a>. For build prerequisites read
<a class="reference internal" href="../admin/buildhosts.html#docs-build"><span class="std std-ref">Build docs</span></a>.</p>
<p>The source files of Searxs documentation are located at <a class="reference external" href="https://github.com/searx/searx/blob/master/docs">git://docs</a>. Sphinx
assumes source files to be encoded in UTF-8 by defaul. Run <a class="reference internal" href="contribution_guide.html#make-docs-live"><span class="std std-ref">make docs.live</span></a> to build HTML while editing.</p>
<div class="sidebar">
<p class="sidebar-title">Further reading</p>
<ul class="simple">
<li><p><a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html">Sphinx-Primer</a></p></li>
<li><p><a class="reference external" href="https://www.sphinx-doc.org/en/stable/markup/index.html">Sphinx markup constructs</a></p></li>
<li><p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reST</a>, <a class="reference external" href="http://docutils.sourceforge.net/docs/index.html">docutils</a>, <a class="reference external" href="http://docutils.sourceforge.net/FAQ.html">docutils FAQ</a></p></li>
<li><p><a class="reference external" href="https://www.sphinx-doc.org">Sphinx</a>, <a class="reference external" href="https://www.sphinx-doc.org/en/stable/faq.html">sphinx-doc FAQ</a></p></li>
<li><p><a class="reference external" href="https://www.sphinx-doc.org/en/stable/config.html">sphinx config</a>, <a class="reference external" href="https://www.sphinx-doc.org/en/master/extdev/tutorial.html?highlight=doctree#build-phases">doctree</a></p></li>
<li><p><a class="reference external" href="https://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations">sphinx cross references</a></p></li>
<li><p><a class="reference external" href="https://return42.github.io/linuxdoc">linuxdoc</a></p></li>
<li><p><a class="reference external" href="https://www.sphinx-doc.org/en/stable/ext/intersphinx.html">intersphinx</a></p></li>
<li><p><a class="reference external" href="https://github.com/tardyp/sphinx-jinja">sphinx-jinja</a></p></li>
<li><p><a class="reference external" href="https://www.sphinx-doc.org/en/stable/ext/autodoc.html">Sphinxs autodoc</a></p></li>
<li><p><a class="reference external" href="https://www.sphinx-doc.org/en/stable/domains.html#the-python-domain">Sphinxs Python domain</a>, <a class="reference external" href="https://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-c-constructs">Sphinxs C domain</a></p></li>
<li><p><a class="reference external" href="https://www.w3.org/TR/SVG11/expanded-toc.html">SVG</a>, <a class="reference external" href="https://www.imagemagick.org">ImageMagick</a></p></li>
<li><p><a class="reference external" href="https://graphviz.gitlab.io/_pages/doc/info/lang.html">DOT</a>, <a class="reference external" href="https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf">Graphvizs dot</a>, <a class="reference external" href="https://graphviz.gitlab.io">Graphviz</a></p></li>
</ul>
</div>
<div class="contents local topic" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><p><a class="reference internal" href="#soft-skills" id="id15">Soft skills</a></p></li>
<li><p><a class="reference internal" href="#basic-inline-markup" id="id16">Basic inline markup</a></p></li>
<li><p><a class="reference internal" href="#basic-article-structure" id="id17">Basic article structure</a></p>
<ul>
<li><p><a class="reference internal" href="#rest-template" id="id18">reST template</a></p></li>
<li><p><a class="reference internal" href="#headings" id="id19">Headings</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#anchors-links" id="id20">Anchors &amp; Links</a></p>
<ul>
<li><p><a class="reference internal" href="#anchors" id="id21">Anchors</a></p></li>
<li><p><a class="reference internal" href="#link-ordinary-url" id="id22">Link ordinary URL</a></p></li>
<li><p><a class="reference internal" href="#smart-refs" id="id23">Smart refs</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#literal-blocks" id="id24">Literal blocks</a></p>
<ul>
<li><p><a class="reference internal" href="#rest-literal" id="id25"><code class="docutils literal notranslate"><span class="pre">::</span></code></a></p></li>
<li><p><a class="reference internal" href="#code-block" id="id26"><code class="docutils literal notranslate"><span class="pre">code-block</span></code></a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#unicode-substitution" id="id27">Unicode substitution</a></p></li>
<li><p><a class="reference internal" href="#roles" id="id28">Roles</a></p></li>
<li><p><a class="reference internal" href="#figures-images" id="id29">Figures &amp; Images</a></p>
<ul>
<li><p><a class="reference internal" href="#dot-files-aka-graphviz" id="id30">DOT files (aka Graphviz)</a></p></li>
<li><p><a class="reference internal" href="#kernel-render-dot" id="id31"><code class="docutils literal notranslate"><span class="pre">kernel-render</span></code> DOT</a></p></li>
<li><p><a class="reference internal" href="#kernel-render-svg" id="id32"><code class="docutils literal notranslate"><span class="pre">kernel-render</span></code> SVG</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#list-markups" id="id33">List markups</a></p>
<ul>
<li><p><a class="reference internal" href="#bullet-list" id="id34">Bullet list</a></p></li>
<li><p><a class="reference internal" href="#horizontal-list" id="id35">Horizontal list</a></p></li>
<li><p><a class="reference internal" href="#definition-list" id="id36">Definition list</a></p></li>
<li><p><a class="reference internal" href="#quoted-paragraphs" id="id37">Quoted paragraphs</a></p></li>
<li><p><a class="reference internal" href="#field-lists" id="id38">Field Lists</a></p></li>
<li><p><a class="reference internal" href="#further-list-blocks" id="id39">Further list blocks</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#admonitions" id="id40">Admonitions</a></p>
<ul>
<li><p><a class="reference internal" href="#sidebar" id="id41">Sidebar</a></p></li>
<li><p><a class="reference internal" href="#generic-admonition" id="id42">Generic admonition</a></p></li>
<li><p><a class="reference internal" href="#specific-admonitions" id="id43">Specific admonitions</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#tables" id="id44">Tables</a></p>
<ul>
<li><p><a class="reference internal" href="#simple-tables" id="id45">Simple tables</a></p></li>
<li><p><a class="reference internal" href="#grid-tables" id="id46">Grid tables</a></p></li>
<li><p><a class="reference internal" href="#flat-table" id="id47">flat-table</a></p></li>
<li><p><a class="reference internal" href="#csv-table" id="id48">CSV table</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#templating" id="id49">Templating</a></p></li>
<li><p><a class="reference internal" href="#tabbed-views" id="id50">Tabbed views</a></p></li>
<li><p><a class="reference internal" href="#math-equations" id="id51">Math equations</a></p></li>
</ul>
</div>
<p><a class="reference external" href="https://www.sphinx-doc.org">Sphinx</a> and <a class="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 <a class="reference external" href="https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html">[kernel doc]</a>.</p>
<div class="sidebar">
<p class="sidebar-title">Content matters</p>
<p>The <a class="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>
<div class="section" id="soft-skills">
<h2><a class="toc-backref" href="#id15">Soft skills</a><a class="headerlink" href="#soft-skills" title="Permalink to this headline"></a></h2>
<p>Before going any deeper into the markup lets face on some <strong>soft skills</strong> a
trained author brings with, to reach a well feedback from readers:</p>
<ul class="simple">
<li><p>Documentation is dedicated to an audience and answers questions from the
audience point of view.</p></li>
<li><p>Dont 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 (<a class="reference external" href="https://github.com/searx/searx/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>
<dl class="simple">
<dt>Users POV: <a class="reference external" href="https://github.com/searx/searx/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>Admins POV: <a class="reference external" href="https://github.com/searx/searx/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 searx setup.</p>
</dd>
<dt>Developers POV: <a class="reference external" href="https://github.com/searx/searx/blob/master/docs/dev">git://docs/dev</a></dt><dd><p>Depending on the <a class="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>
<div class="section" id="basic-inline-markup">
<span id="rest-inline-markup"></span><h2><a class="toc-backref" href="#id16">Basic inline markup</a><a class="headerlink" href="#basic-inline-markup" title="Permalink to this headline"></a></h2>
<div class="sidebar">
<p class="sidebar-title">Inline markup</p>
<ul class="simple">
<li><p><a class="reference internal" href="#rest-roles"><span class="std std-ref">Roles</span></a></p></li>
<li><p><a class="reference internal" href="#rest-smart-ref"><span class="std std-ref">Smart refs</span></a></p></li>
</ul>
</div>
<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 (<code class="docutils literal notranslate"><span class="pre">\*pointer</span></code>).</p>
<table class="colwidths-given docutils align-default" id="id4">
<caption><span class="caption-number">Table 3 </span><span class="caption-text">basic inline markup</span><a class="headerlink" href="#id4" title="Permalink to this table"></a></caption>
<colgroup>
<col style="width: 29%" />
<col style="width: 21%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>description</p></th>
<th class="head"><p>rendered</p></th>
<th class="head"><p>markup</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>one asterisk for emphasis</p></td>
<td><p><em>italics</em></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">*italics*</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>two asterisks for strong emphasis</p></td>
<td><p><strong>boldface</strong></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">**boldface**</span></code></p></td>
</tr>
<tr class="row-even"><td><p>backquotes for code samples and literals</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">foo()</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">``foo()``</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>quote asterisks or backquotes</p></td>
<td><p>*foo is a pointer</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">\*foo</span> <span class="pre">is</span> <span class="pre">a</span> <span class="pre">pointer</span></code></p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="basic-article-structure">
<span id="rest-basic-structure"></span><h2><a class="toc-backref" href="#id17">Basic article structure</a><a class="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>
<div class="section" id="rest-template">
<span id="id2"></span><h3><a class="toc-backref" href="#id18">reST template</a><a class="headerlink" href="#rest-template" title="Permalink to this headline"></a></h3>
<p>reST template for an simple article:</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_doc refname:</span>
<span class="gh">==============</span>
<span class="gh">Document title</span>
<span class="gh">==============</span>
Lorem ipsum dolor sit amet, consectetur adipisici elit .. Further read
<span class="na">:ref:</span><span class="nv">`chapter refname`</span>.
<span class="p">..</span> <span class="nt">_chapter refname:</span>
<span class="gh">Chapter</span>
<span class="gh">=======</span>
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquid ex ea commodi consequat ...
<span class="p">..</span> <span class="nt">_section refname:</span>
<span class="gh">Section</span>
<span class="gh">-------</span>
lorem ..
<span class="p">..</span> <span class="nt">_subsection refname:</span>
<span class="gh">Subsection</span>
<span class="gh">~~~~~~~~~~</span>
lorem ..
</pre></div>
</div>
</div>
<div class="section" id="headings">
<h3><a class="toc-backref" href="#id19">Headings</a><a class="headerlink" href="#headings" title="Permalink to this headline"></a></h3>
<ol class="arabic simple">
<li><p>title - with overline for document title:</p></li>
</ol>
<blockquote>
<div><div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="gh">==============</span>
<span class="gh">Document title</span>
<span class="gh">==============</span>
</pre></div>
</div>
</div></blockquote>
<ol class="arabic">
<li><p>chapter - with anchor named <code class="docutils literal notranslate"><span class="pre">anchor</span> <span class="pre">name</span></code>:</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_anchor name:</span>
<span class="gh">Chapter</span>
<span class="gh">=======</span>
</pre></div>
</div>
</li>
<li><p>section</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="gh">Section</span>
<span class="gh">-------</span>
</pre></div>
</div>
</li>
<li><p>subsection</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="gh">Subsection</span>
<span class="gh">~~~~~~~~~~</span>
</pre></div>
</div>
</li>
</ol>
</div>
</div>
<div class="section" id="anchors-links">
<h2><a class="toc-backref" href="#id20">Anchors &amp; Links</a><a class="headerlink" href="#anchors-links" title="Permalink to this headline"></a></h2>
<div class="section" id="anchors">
<span id="rest-anchor"></span><h3><a class="toc-backref" href="#id21">Anchors</a><a class="headerlink" href="#anchors" title="Permalink to this headline"></a></h3>
<p>To refer a point in the documentation a anchor is needed. The <a class="reference internal" href="#rest-template"><span class="std std-ref">reST
template</span></a> shows an example where a chapter titled <em>“Chapters”</em>
gets an anchor named <code class="docutils literal notranslate"><span class="pre">chapter</span> <span class="pre">title</span></code>. Another example from <em>this</em> document,
where the anchor named <code class="docutils literal notranslate"><span class="pre">reST</span> <span class="pre">anchor</span></code>:</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_reST anchor:</span>
<span class="gh">Anchors</span>
<span class="gh">-------</span>
To refer a point in the documentation a anchor is needed ...
</pre></div>
</div>
<p>To refer anchors use the <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref">ref role</a> markup:</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span>Visit chapter <span class="na">:ref:</span><span class="nv">`reST anchor`</span>. Or set hyperlink text manualy :ref:`foo
bar &lt;reST anchor&gt;`.
</pre></div>
</div>
<div class="rst-example admonition">
<p class="admonition-title"><code class="docutils literal notranslate"><span class="pre">:ref:</span></code> role</p>
<p>Visist chapter <a class="reference internal" href="#rest-anchor"><span class="std std-ref">Anchors</span></a>. Or set hyperlink text manualy <a class="reference internal" href="#rest-anchor"><span class="std std-ref">foo
bar</span></a>.</p>
</div>
</div>
<div class="section" id="link-ordinary-url">
<span id="rest-ordinary-ref"></span><h3><a class="toc-backref" href="#id22">Link ordinary URL</a><a class="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>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_Sphinx Field Lists:</span>
https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
With the <span class="ge">*named*</span> hyperlink <span class="s">`Sphinx Field Lists`_</span>, the raw text is much more
readable.
And this shows the alternative (less readable) hyperlink markup `Sphinx Field
Lists
<span class="nt">&lt;https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html&gt;</span>`__.
</pre></div>
</div>
<div class="rst-example admonition">
<p class="admonition-title">Named hyperlink</p>
<p>With the <em>named</em> hyperlink <a class="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 <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html">Sphinx Field
Lists</a>.</p>
</div>
</div>
<div class="section" id="smart-refs">
<span id="rest-smart-ref"></span><h3><a class="toc-backref" href="#id23">Smart refs</a><a class="headerlink" href="#smart-refs" title="Permalink to this headline"></a></h3>
<p>With the power of <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html">sphinx.ext.extlinks</a> and <a class="reference external" href="https://www.sphinx-doc.org/en/stable/ext/intersphinx.html">intersphinx</a> referencing external
content becomes smart.</p>
<table class="colwidths-given docutils align-default" id="id5">
<caption><span class="caption-number">Table 4 </span><span class="caption-text">smart refs with <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html">sphinx.ext.extlinks</a> and <a class="reference external" href="https://www.sphinx-doc.org/en/stable/ext/intersphinx.html">intersphinx</a></span><a class="headerlink" href="#id5" title="Permalink to this table"></a></caption>
<colgroup>
<col style="width: 29%" />
<col style="width: 21%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>refer …</p></th>
<th class="head"><p>rendered example</p></th>
<th class="head"><p>markup</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-rfc" title="(in Sphinx v6.0.0)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">rfc</span></code></a></p></td>
<td><p><span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc822.html"><strong>RFC 822</strong></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:rfc:`822`</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-pep" title="(in Sphinx v6.0.0)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">pep</span></code></a></p></td>
<td><p><span class="target" id="index-1"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0008"><strong>PEP 8</strong></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:pep:`8`</span></code></p></td>
</tr>
<tr class="row-even"><td colspan="3"><p><a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html">sphinx.ext.extlinks</a></p></td>
</tr>
<tr class="row-odd"><td><p>projects wiki article</p></td>
<td><p><a class="reference external" href="https://github.com/searx/searx/wiki/Offline-engines"> Offline-engines</a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:wiki:`Offline-engines`</span></code></p></td>
</tr>
<tr class="row-even"><td><p>to docs public URL</p></td>
<td><p><a class="reference external" href="https://searx.github.io/searx/dev/reST.html">docs: dev/reST.html</a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:docs:`dev/reST.html`</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>files &amp; folders origin</p></td>
<td><p><a class="reference external" href="https://github.com/searx/searx/blob/master/docs/dev/reST.rst">git://docs/dev/reST.rst</a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:origin:`docs/dev/reST.rst`</span></code></p></td>
</tr>
<tr class="row-even"><td><p>pull request</p></td>
<td><p><a class="reference external" href="https://github.com/searx/searx/pull/1756">PR 1756</a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:pull:`1756`</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>patch</p></td>
<td><p><a class="reference external" href="https://github.com/searx/searx/commit/af2cae6">#af2cae6</a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:patch:`af2cae6`</span></code></p></td>
</tr>
<tr class="row-even"><td><p>PyPi package</p></td>
<td><p><a class="reference external" href="https://pypi.org/project/searx">PyPi: searx</a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:pypi:`searx`</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>manual page man</p></td>
<td><p><a class="reference external" href="https://manpages.debian.org/jump?q=bash">bash</a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:man:`bash`</span></code></p></td>
</tr>
<tr class="row-even"><td colspan="3"><p><a class="reference external" href="https://www.sphinx-doc.org/en/stable/ext/intersphinx.html">intersphinx</a></p></td>
</tr>
<tr class="row-odd"><td><p>external anchor</p></td>
<td><p><a class="reference external" href="https://docs.python.org/3/reference/expressions.html#and" title="(in Python v3.10)"><span>Boolean operations</span></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:ref:`python:and`</span></code></p></td>
</tr>
<tr class="row-even"><td><p>external doc anchor</p></td>
<td><p><a class="reference external" href="https://jinja.palletsprojects.com/en/3.1.x/templates/" title="(in Jinja v3.1.x)"><span>Template Designer Documentation</span></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:doc:`jinja:templates`</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>python code object</p></td>
<td><p><a class="reference external" href="https://docs.python.org/3/library/datetime.html#datetime.datetime" title="(in Python v3.10)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">datetime.datetime</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:py:obj:`datetime.datetime`</span></code></p></td>
</tr>
<tr class="row-even"><td><p>flask code object</p></td>
<td><p><a class="reference external" href="https://flask.palletsprojects.com/en/2.1.x/api/#flask.Flask" title="(in Flask v2.1.x)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">flask.Flask</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:py:obj:`flask.Flask`</span></code></p></td>
</tr>
</tbody>
</table>
<p>Intersphinx is configured in <a class="reference external" href="https://github.com/searx/searx/blob/master/docs/conf.py">git://docs/conf.py</a>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">intersphinx_mapping</span> <span class="o">=</span> <span class="p">{</span>
<span class="s2">&quot;python&quot;</span><span class="p">:</span> <span class="p">(</span><span class="s2">&quot;https://docs.python.org/3/&quot;</span><span class="p">,</span> <span class="kc">None</span><span class="p">),</span>
<span class="s2">&quot;flask&quot;</span><span class="p">:</span> <span class="p">(</span><span class="s2">&quot;https://flask.palletsprojects.com/&quot;</span><span class="p">,</span> <span class="kc">None</span><span class="p">),</span>
<span class="s2">&quot;jinja&quot;</span><span class="p">:</span> <span class="p">(</span><span class="s2">&quot;https://jinja.palletsprojects.com/&quot;</span><span class="p">,</span> <span class="kc">None</span><span class="p">),</span>
<span class="s2">&quot;linuxdoc&quot;</span> <span class="p">:</span> <span class="p">(</span><span class="s2">&quot;https://return42.github.io/linuxdoc/&quot;</span><span class="p">,</span> <span class="kc">None</span><span class="p">),</span>
<span class="s2">&quot;sphinx&quot;</span> <span class="p">:</span> <span class="p">(</span><span class="s2">&quot;https://www.sphinx-doc.org/en/master/&quot;</span><span class="p">,</span> <span class="kc">None</span><span class="p">),</span>
<span class="p">}</span>
</pre></div>
</div>
<p>To list all anchors of the inventory (e.g. <code class="docutils literal notranslate"><span class="pre">python</span></code>) use:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
...
$ python -m sphinx.ext.intersphinx https://searx.github.io/searx/objects.inv
...
</pre></div>
</div>
</div>
</div>
<div class="section" id="literal-blocks">
<h2><a class="toc-backref" href="#id24">Literal blocks</a><a class="headerlink" href="#literal-blocks" title="Permalink to this headline"></a></h2>
<p>The simplest form of <a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#literal-blocks">literal-blocks</a> is a indented block introduced by
two colons (<code class="docutils literal notranslate"><span class="pre">::</span></code>). For highlighting use <a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/directives.html#highlight">highlight</a> or <a class="reference internal" href="#rest-code"><span class="std std-ref">code-block</span></a> directive. To include literals from external files use
<a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude" title="(in Sphinx v6.0.0)"><code class="xref rst rst-dir docutils literal notranslate"><span class="pre">literalinclude</span></code></a> or <a class="reference external" href="https://return42.github.io/linuxdoc/linuxdoc-howto/kernel-include-directive.html#kernel-include-directive" title="(in LinuxDoc v20210324)"><span class="xref std std-ref">kernel-include</span></a>
directive (latter one expands environment variables in the path name).</p>
<div class="section" id="rest-literal">
<span id="id3"></span><h3><a class="toc-backref" href="#id25"><code class="docutils literal notranslate"><span class="pre">::</span></code></a><a class="headerlink" href="#rest-literal" title="Permalink to this headline"></a></h3>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="se">::</span>
<span class="s"> Literal block</span>
Lorem ipsum dolor<span class="se">::</span>
<span class="s"> Literal block</span>
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
eirmod tempor invidunt ut labore ::
Literal block
</pre></div>
</div>
<div class="rst-example admonition">
<p class="admonition-title">Literal block</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Literal block
</pre></div>
</div>
<p>Lorem ipsum dolor:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Literal block
</pre></div>
</div>
<p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
eirmod tempor invidunt ut labore</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Literal block
</pre></div>
</div>
</div>
</div>
<div class="section" id="code-block">
<span id="rest-code"></span><h3><a class="toc-backref" href="#id26"><code class="docutils literal notranslate"><span class="pre">code-block</span></code></a><a class="headerlink" href="#code-block" title="Permalink to this headline"></a></h3>
<div class="sidebar">
<p class="sidebar-title">Syntax highlighting</p>
<p>is handled by <a class="reference external" href="https://pygments.org/languages/">pygments</a>.</p>
</div>
<p>The <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block" title="(in Sphinx v6.0.0)"><code class="xref rst rst-dir docutils literal notranslate"><span class="pre">code-block</span></code></a> directive is a variant of the <a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/directives.html#code">code</a> directive
with additional options. To learn more about code literals visit
<a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#code-examples" title="(in Sphinx v6.0.0)"><span>Showing code examples</span></a>.</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span>The URL <span class="s">``/stats``</span> handle is shown in <span class="na">:ref:</span><span class="nv">`stats-handle`</span>
<span class="p">..</span> <span class="ow">code-block</span><span class="p">::</span> Python
<span class="nc">:caption:</span> python code block
<span class="nc">:name:</span> stats-handle
@app.route(&#39;/stats&#39;, methods=[&#39;GET&#39;])
def stats():
&quot;&quot;&quot;Render engine statistics page.&quot;&quot;&quot;
stats = get_engines_stats()
return render(
&#39;stats.html&#39;
, stats = stats )
</pre></div>
</div>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span>
</pre></div>
</div>
<div class="rst-example admonition">
<p class="admonition-title">Code block</p>
<p>The URL <code class="docutils literal notranslate"><span class="pre">/stats</span></code> handle is shown in <a class="reference internal" href="#stats-handle"><span class="std std-ref">python code block</span></a></p>
<div class="literal-block-wrapper docutils container" id="stats-handle">
<div class="code-block-caption"><span class="caption-number">Listing 1 </span><span class="caption-text">python code block</span><a class="headerlink" href="#stats-handle" title="Permalink to this code"></a></div>
<div class="highlight-Python notranslate"><div class="highlight"><pre><span></span><span class="nd">@app</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s1">&#39;/stats&#39;</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;GET&#39;</span><span class="p">])</span>
<span class="k">def</span> <span class="nf">stats</span><span class="p">():</span>
<span class="sd">&quot;&quot;&quot;Render engine statistics page.&quot;&quot;&quot;</span>
<span class="n">stats</span> <span class="o">=</span> <span class="n">get_engines_stats</span><span class="p">()</span>
<span class="k">return</span> <span class="n">render</span><span class="p">(</span>
<span class="s1">&#39;stats.html&#39;</span>
<span class="p">,</span> <span class="n">stats</span> <span class="o">=</span> <span class="n">stats</span> <span class="p">)</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
<div class="section" id="unicode-substitution">
<h2><a class="toc-backref" href="#id27">Unicode substitution</a><a class="headerlink" href="#unicode-substitution" title="Permalink to this headline"></a></h2>
<p>The <a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/directives.html#unicode-character-codes">unicode directive</a> converts Unicode
character codes (numerical values) to characters. This directive can only be
used within a substitution definition.</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">|copy|</span> <span class="ow">unicode</span><span class="p">::</span> 0xA9 .. copyright sign
<span class="p">..</span> <span class="nt">|(TM)|</span> <span class="ow">unicode</span><span class="p">::</span> U+2122
Trademark |(TM)| and copyright |copy| glyphs.
</pre></div>
</div>
<div class="rst-example admonition">
<p class="admonition-title">Unicode</p>
<p>Trademark ™ and copyright © glyphs.</p>
</div>
</div>
<div class="section" id="roles">
<span id="rest-roles"></span><h2><a class="toc-backref" href="#id28">Roles</a><a class="headerlink" href="#roles" title="Permalink to this headline"></a></h2>
<div class="sidebar">
<p class="sidebar-title">Further reading</p>
<ul class="simple">
<li><p><a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html">Sphinx Roles</a></p></li>
<li><p><a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html" title="(in Sphinx v6.0.0)"><span>Domains</span></a></p></li>
</ul>
</div>
<p>A <em>custom interpreted text role</em> (<a class="reference external" href="https://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
in a specific way.</p>
<p>The general markup is one of:</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="na">:rolename:</span><span class="nv">`ref-name`</span>
<span class="na">:rolename:</span><span class="nv">`ref text &lt;ref-name&gt;`</span>
</pre></div>
</div>
<table class="colwidths-given docutils align-default" id="id6">
<caption><span class="caption-number">Table 5 </span><span class="caption-text">smart refs with <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html">sphinx.ext.extlinks</a> and <a class="reference external" href="https://www.sphinx-doc.org/en/stable/ext/intersphinx.html">intersphinx</a></span><a class="headerlink" href="#id6" title="Permalink to this table"></a></caption>
<colgroup>
<col style="width: 29%" />
<col style="width: 21%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>role</p></th>
<th class="head"><p>rendered example</p></th>
<th class="head"><p>markup</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-guilabel" title="(in Sphinx v6.0.0)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">guilabel</span></code></a></p></td>
<td><p><span class="guilabel"><span class="accelerator">C</span>ancel</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:guilabel:`&amp;Cancel`</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-kbd" title="(in Sphinx v6.0.0)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">kbd</span></code></a></p></td>
<td><p><kbd class="kbd compound docutils literal notranslate"><kbd class="kbd docutils literal notranslate">C</kbd>-<kbd class="kbd docutils literal notranslate">x</kbd> <kbd class="kbd docutils literal notranslate">C</kbd>-<kbd class="kbd docutils literal notranslate">f</kbd></kbd></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:kbd:`C-x</span> <span class="pre">C-f`</span></code></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-menuselection" title="(in Sphinx v6.0.0)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">menuselection</span></code></a></p></td>
<td><p><span class="menuselection">Open ‣ File</span></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:menuselection:`Open</span> <span class="pre">--&gt;</span> <span class="pre">File`</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-download" title="(in Sphinx v6.0.0)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">download</span></code></a></p></td>
<td><p><a class="reference download internal" download="" href="../_downloads/ad0ebe55d6b53b1559e0ca8dee6f30b9/reST.rst"><code class="xref download docutils literal notranslate"><span class="pre">this</span> <span class="pre">file</span></code></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:download:`this</span> <span class="pre">file</span> <span class="pre">&lt;reST.rst&gt;`</span></code></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="#math">math</a></p></td>
<td><p><img class="math" src="../_images/math/6673b43f9fe29455c1fcd1164e5844698cc64d38.svg" alt="a^2 + b^2 = c^2"/></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:math:`a^2</span> <span class="pre">+</span> <span class="pre">b^2</span> <span class="pre">=</span> <span class="pre">c^2`</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref" title="(in Sphinx v6.0.0)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">ref</span></code></a></p></td>
<td><p><a class="reference internal" href="#svg-image-example"><span class="std std-ref">Simple SVG image.</span></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:ref:`svg</span> <span class="pre">image</span> <span class="pre">example`</span></code></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-command" title="(in Sphinx v6.0.0)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">command</span></code></a></p></td>
<td><p><strong class="command">ls -la</strong></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:command:`ls</span> <span class="pre">-la`</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/roles.html#emphasis">emphasis</a></p></td>
<td><p><em>italic</em></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:emphasis:`italic`</span></code></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/roles.html#strong">strong</a></p></td>
<td><p><strong>bold</strong></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:strong:`bold`</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/roles.html#literal">literal</a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">foo()</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:literal:`foo()`</span></code></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/roles.html#subscript">subscript</a></p></td>
<td><p>H<sub>2</sub>O</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">H\</span> <span class="pre">:sub:`2`\</span> <span class="pre">O</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/roles.html#superscript">superscript</a></p></td>
<td><p>E = mc<sup>2</sup></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">E</span> <span class="pre">=</span> <span class="pre">mc\</span> <span class="pre">:sup:`2`</span></code></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/roles.html#title-reference">title-reference</a></p></td>
<td><p><cite>Time</cite></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">:title:`Time`</span></code></p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="figures-images">
<h2><a class="toc-backref" href="#id29">Figures &amp; Images</a><a class="headerlink" href="#figures-images" title="Permalink to this headline"></a></h2>
<div class="sidebar">
<p class="sidebar-title">Image processing</p>
<p>With the directives from <a class="reference external" href="https://return42.github.io/linuxdoc/linuxdoc-howto/kfigure.html#kfigure" title="(in LinuxDoc v20210324)"><span class="xref std std-ref">linuxdoc</span></a> the build process
is flexible. To get best results in the generated output format, install
<a class="reference external" href="https://www.imagemagick.org">ImageMagick</a> and <a class="reference external" href="https://graphviz.gitlab.io">Graphviz</a>.</p>
</div>
<p>Searxs sphinx setup includes: <a class="reference external" href="https://return42.github.io/linuxdoc/linuxdoc-howto/kfigure.html#kfigure" title="(in LinuxDoc v20210324)"><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 its annoying to care
about the build process when handling with images, especially since he has no
access to the build process. With <a class="reference external" href="https://return42.github.io/linuxdoc/linuxdoc-howto/kfigure.html#kfigure" title="(in LinuxDoc v20210324)"><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 <code class="docutils literal notranslate"><span class="pre">kernel-figure</span></code> (inheritance
of <a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/directives.html#figure">figure</a>) and <code class="docutils literal notranslate"><span class="pre">kernel-image</span></code> (inheritance of <a class="reference external" href="https://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
(<a class="reference internal" href="#svg-image-example"><span class="std std-ref">Simple SVG image.</span></a>):</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_svg image example:</span>
<span class="p">..</span> <span class="ow">kernel-figure</span><span class="p">::</span> svg_image.svg
<span class="nc">:alt:</span> SVG image example
Simple SVG image
To refer the figure, a caption block is needed: <span class="na">:ref:</span><span class="nv">`svg image example`</span>.
</pre></div>
</div>
<div class="figure align-default" id="id7">
<img alt="SVG image example" src="../_images/svg_image.svg" /><p class="caption"><span class="caption-number">Fig. 2 </span><span class="caption-text">Simple SVG image.</span><a class="headerlink" href="#id7" title="Permalink to this image"></a></p>
</div>
<p>To refer the figure, a caption block is needed: <a class="reference internal" href="#svg-image-example"><span class="std std-ref">Simple SVG image.</span></a>.</p>
<div class="section" id="dot-files-aka-graphviz">
<h3><a class="toc-backref" href="#id30">DOT files (aka Graphviz)</a><a class="headerlink" href="#dot-files-aka-graphviz" title="Permalink to this headline"></a></h3>
<p>With <a class="reference external" href="https://return42.github.io/linuxdoc/linuxdoc-howto/kfigure.html#kernel-figure" title="(in LinuxDoc v20210324)"><span>kernel-figure &amp; kernel-image</span></a> reST support for <strong>DOT</strong> formatted files is
given.</p>
<ul class="simple">
<li><p><a class="reference external" href="https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf">Graphvizs dot</a></p></li>
<li><p><a class="reference external" href="https://graphviz.gitlab.io/_pages/doc/info/lang.html">DOT</a></p></li>
<li><p><a class="reference external" href="https://graphviz.gitlab.io">Graphviz</a></p></li>
</ul>
<p>A simple example is shown in <a class="reference internal" href="#dot-file-example"><span class="std std-ref">DOTs hello world example</span></a>:</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_dot file example:</span>
<span class="p">..</span> <span class="ow">kernel-figure</span><span class="p">::</span> hello.dot
<span class="nc">:alt:</span> hello world
DOT&#39;s hello world example
</pre></div>
</div>
<div class="rst-example admonition">
<p class="admonition-title">hello.dot</p>
<div class="figure align-default" id="id8">
<img alt="hello world" src="../_images/hello.svg" /><p class="caption"><span class="caption-number">Fig. 3 </span><span class="caption-text">DOTs hello world example</span><a class="headerlink" href="#id8" title="Permalink to this image"></a></p>
</div>
</div>
</div>
<div class="section" id="kernel-render-dot">
<h3><a class="toc-backref" href="#id31"><code class="docutils literal notranslate"><span class="pre">kernel-render</span></code> DOT</a><a class="headerlink" href="#kernel-render-dot" title="Permalink to this headline"></a></h3>
<p>Embed <em>render</em> markups (or languages) like Graphvizs <strong>DOT</strong> is provided by the
<a class="reference external" href="https://return42.github.io/linuxdoc/linuxdoc-howto/kfigure.html#kernel-render" title="(in LinuxDoc v20210324)"><span>kernel-render</span></a> directive. A simple example of embedded <a class="reference external" href="https://graphviz.gitlab.io/_pages/doc/info/lang.html">DOT</a> is
shown in figure <a class="reference internal" href="#dot-render-example"><span class="std std-ref">Embedded DOT (Graphviz) code</span></a>:</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_dot render example:</span>
<span class="p">..</span> <span class="ow">kernel-render</span><span class="p">::</span> DOT
<span class="nc">:alt:</span> digraph
<span class="nc">:caption:</span> Embedded DOT (Graphviz) code
digraph foo {
&quot;bar&quot; -&gt; &quot;baz&quot;;
}
Attribute <span class="s">``caption``</span> is needed, if you want to refer the figure: :ref:`dot
render example`.
</pre></div>
</div>
<p>Please note <a class="reference external" href="https://return42.github.io/linuxdoc/linuxdoc-howto/kfigure.html#kfigure-build-tools" title="(in LinuxDoc v20210324)"><span class="xref std std-ref">build tools</span></a>. If <a class="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>
<div class="rst-example admonition">
<p class="admonition-title">kernel-render DOT</p>
<div class="figure align-default" id="id9">
<span id="dot-render-example"></span><img alt="digraph" src="../_images/DOT-57a4a7f78690d0b6b884bc59f36e84cfb0b61f76.svg" /><p class="caption"><span class="caption-number">Fig. 4 </span><span class="caption-text">Embedded DOT (Graphviz) code</span><a class="headerlink" href="#id9" title="Permalink to this image"></a></p>
</div>
<p>Attribute <code class="docutils literal notranslate"><span class="pre">caption</span></code> is needed, if you want to refer the figure: <a class="reference internal" href="#dot-render-example"><span class="std std-ref">Embedded DOT (Graphviz) code</span></a>.</p>
</div>
</div>
<div class="section" id="kernel-render-svg">
<h3><a class="toc-backref" href="#id32"><code class="docutils literal notranslate"><span class="pre">kernel-render</span></code> SVG</a><a class="headerlink" href="#kernel-render-svg" title="Permalink to this headline"></a></h3>
<p>A simple example of embedded <a class="reference external" href="https://www.w3.org/TR/SVG11/expanded-toc.html">SVG</a> is shown in figure <a class="reference internal" href="#svg-render-example"><span class="std std-ref">Embedded SVG markup</span></a>:</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_svg render example:</span>
<span class="p">..</span> <span class="ow">kernel-render</span><span class="p">::</span> SVG
<span class="nc">:caption:</span> Embedded <span class="gs">**SVG**</span> markup
<span class="nc">:alt:</span> so-nw-arrow
</pre></div>
</div>
<blockquote>
<div><div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
<span class="nt">&lt;svg</span> <span class="na">xmlns=</span><span class="s">&quot;http://www.w3.org/2000/svg&quot;</span> <span class="na">version=</span><span class="s">&quot;1.1&quot;</span>
<span class="na">baseProfile=</span><span class="s">&quot;full&quot;</span> <span class="na">width=</span><span class="s">&quot;70px&quot;</span> <span class="na">height=</span><span class="s">&quot;40px&quot;</span>
<span class="na">viewBox=</span><span class="s">&quot;0 0 700 400&quot;</span>
<span class="nt">&gt;</span>
<span class="nt">&lt;line</span> <span class="na">x1=</span><span class="s">&quot;180&quot;</span> <span class="na">y1=</span><span class="s">&quot;370&quot;</span>
<span class="na">x2=</span><span class="s">&quot;500&quot;</span> <span class="na">y2=</span><span class="s">&quot;50&quot;</span>
<span class="na">stroke=</span><span class="s">&quot;black&quot;</span> <span class="na">stroke-width=</span><span class="s">&quot;15px&quot;</span>
<span class="nt">/&gt;</span>
<span class="nt">&lt;polygon</span> <span class="na">points=</span><span class="s">&quot;585 0 525 25 585 50&quot;</span>
<span class="na">transform=</span><span class="s">&quot;rotate(135 525 25)&quot;</span>
<span class="nt">/&gt;</span>
<span class="nt">&lt;/svg&gt;</span>
</pre></div>
</div>
</div></blockquote>
<div class="rst-example admonition">
<p class="admonition-title">kernel-render SVG</p>
<div class="figure align-default" id="id10">
<span id="svg-render-example"></span><img alt="so-nw-arrow" src="../_images/SVG-1fb7029fa2cc454a267bae271cccb2c591387416.svg" /><p class="caption"><span class="caption-number">Fig. 5 </span><span class="caption-text">Embedded <strong>SVG</strong> markup</span><a class="headerlink" href="#id10" title="Permalink to this image"></a></p>
</div>
</div>
</div>
</div>
<div class="section" id="list-markups">
<span id="rest-lists"></span><h2><a class="toc-backref" href="#id33">List markups</a><a class="headerlink" href="#list-markups" title="Permalink to this headline"></a></h2>
<div class="section" id="bullet-list">
<h3><a class="toc-backref" href="#id34">Bullet list</a><a class="headerlink" href="#bullet-list" title="Permalink to this headline"></a></h3>
<p>List markup (<a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists">ref</a>) is simple:</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="m">-</span> This is a bulleted list.
<span class="m">1.</span> Nested lists are possible, but be aware that they must be separated from
the parent list items by blank line
<span class="m">2.</span> Second item of nested list
<span class="m">-</span> It has two items, the second
item uses two lines.
<span class="m">#.</span> This is a numbered list.
<span class="m">#.</span> It has two items too.
</pre></div>
</div>
<div class="rst-example admonition">
<p class="admonition-title">bullet list</p>
<ul class="simple">
<li><p>This is a bulleted list.</p>
<ol class="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>
<ol class="arabic simple">
<li><p>This is a numbered list.</p></li>
<li><p>It has two items too.</p></li>
</ol>
</div>
</div>
<div class="section" id="horizontal-list">
<h3><a class="toc-backref" href="#id35">Horizontal list</a><a class="headerlink" href="#horizontal-list" title="Permalink to this headline"></a></h3>
<p>The <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-hlist" title="(in Sphinx v6.0.0)"><code class="xref rst rst-dir docutils literal notranslate"><span class="pre">..</span> <span class="pre">hlist::</span></code></a> transforms a bullet list into a more compact
list.</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">hlist</span><span class="p">::</span>
<span class="m">-</span> first list item
<span class="m">-</span> second list item
<span class="m">-</span> third list item
<span class="cp"> ...</span>
</pre></div>
</div>
<div class="rst-example admonition">
<p class="admonition-title">hlist</p>
<table class="hlist"><tr><td><ul class="simple">
<li><p>first list item</p></li>
<li><p>second list item</p></li>
<li><p>third list item</p></li>
<li><p>next list item</p></li>
</ul>
</td><td><ul class="simple">
<li><p>next list item xxxx</p></li>
<li><p>next list item yyyy</p></li>
<li><p>next list item zzzz</p></li>
</ul>
</td></tr></table>
</div>
</div>
<div class="section" id="definition-list">
<h3><a class="toc-backref" href="#id36">Definition list</a><a class="headerlink" href="#definition-list" title="Permalink to this headline"></a></h3>
<div class="sidebar">
<p class="sidebar-title">Note ..</p>
<ul class="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 (<a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#definition-lists">ref</a>) from block
quotes (<a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#block-quotes">ref</a>).</p></li>
</ul>
</div>
<p>Each definition list (<a class="reference external" href="https://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>
<div class="highlight-reST notranslate"><div class="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&#39;s definition. <span class="gs">**There is a blank line**</span> in between
the line above and this paragraph. That&#39;s why this paragraph is taken as
<span class="gs">**block quote**</span> (<span class="na">:duref:</span><span class="nv">`ref &lt;block-quotes&gt;`</span>) and not as term&#39;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>
<div class="rst-example admonition">
<p class="admonition-title">definition list</p>
<dl class="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 terms definition. <strong>There is a blank line</strong> in between
the line above and this paragraph. Thats why this paragraph is taken as
<strong>block quote</strong> (<a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#block-quotes">ref</a>) and not as terms definition!</p>
</div></blockquote>
<dl>
<dt>term 2</dt><dd><p>Definition 2, paragraph 1.</p>
<p>Definition 2, paragraph 2.</p>
</dd>
<dt>term 3<span class="classifier">classifier</span></dt><dd><p>Definition 3.</p>
</dd>
</dl>
<p>term 4 : classifier one : classifier two</p>
</div>
</div>
<div class="section" id="quoted-paragraphs">
<h3><a class="toc-backref" href="#id37">Quoted paragraphs</a><a class="headerlink" href="#quoted-paragraphs" title="Permalink to this headline"></a></h3>
<p>Quoted paragraphs (<a class="reference external" href="https://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 (<a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#line-blocks">ref</a>) are a way of preserving line breaks:</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span>normal paragraph ...
lorem ipsum.
Quoted paragraph ...
lorem ipsum.
<span class="o">|</span> These lines are
<span class="o">|</span> broken exactly like in
<span class="o">|</span> the source file.
</pre></div>
</div>
<div class="rst-example admonition">
<p class="admonition-title">Quoted paragraph and line block</p>
<p>normal paragraph …
lorem ipsum.</p>
<blockquote>
<div><p>Quoted paragraph …
lorem ipsum.</p>
</div></blockquote>
<div class="line-block">
<div class="line">These lines are</div>
<div class="line">broken exactly like in</div>
<div class="line">the source file.</div>
</div>
</div>
</div>
<div class="section" id="field-lists">
<span id="rest-field-list"></span><h3><a class="toc-backref" href="#id38">Field Lists</a><a class="headerlink" href="#field-lists" title="Permalink to this headline"></a></h3>
<div class="sidebar">
<p class="sidebar-title">bibliographic fields</p>
<p>First lines fields are bibliographic fields, see <a class="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>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="nc">:fieldname:</span> Field content
<span class="nc">:foo:</span> first paragraph in field foo
second paragraph in field foo
<span class="nc">:bar:</span> Field content
</pre></div>
</div>
<div class="rst-example admonition">
<p class="admonition-title">Field List</p>
<dl class="field-list">
<dt class="field-odd">fieldname</dt>
<dd class="field-odd"><p>Field content</p>
</dd>
<dt class="field-even">foo</dt>
<dd class="field-even"><p>first paragraph in field foo</p>
<p>second paragraph in field foo</p>
</dd>
<dt class="field-odd">bar</dt>
<dd class="field-odd"><p>Field content</p>
</dd>
</dl>
</div>
<p>They are commonly used in Python documentation:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">my_function</span><span class="p">(</span><span class="n">my_arg</span><span class="p">,</span> <span class="n">my_other_arg</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;A function just for me.</span>
<span class="sd"> :param my_arg: The first of my arguments.</span>
<span class="sd"> :param my_other_arg: The second of my arguments.</span>
<span class="sd"> :returns: A message (just for me, of course).</span>
<span class="sd"> &quot;&quot;&quot;</span>
</pre></div>
</div>
</div>
<div class="section" id="further-list-blocks">
<h3><a class="toc-backref" href="#id39">Further list blocks</a><a class="headerlink" href="#further-list-blocks" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><p>field lists (<a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists">ref</a>, with caveats noted in
<a class="reference internal" href="#rest-field-list"><span class="std std-ref">Field Lists</span></a>)</p></li>
<li><p>option lists (<a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#option-lists">ref</a>)</p></li>
<li><p>quoted literal blocks (<a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#quoted-literal-blocks">ref</a>)</p></li>
<li><p>doctest blocks (<a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#doctest-blocks">ref</a>)</p></li>
</ul>
</div>
</div>
<div class="section" id="admonitions">
<h2><a class="toc-backref" href="#id40">Admonitions</a><a class="headerlink" href="#admonitions" title="Permalink to this headline"></a></h2>
<div class="section" id="sidebar">
<h3><a class="toc-backref" href="#id41">Sidebar</a><a class="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 <a class="reference internal" href="#rest-primer"><span class="std std-ref">on top of this page</span></a>.</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">sidebar</span><span class="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>
<div class="section" id="generic-admonition">
<h3><a class="toc-backref" href="#id42">Generic admonition</a><a class="headerlink" href="#generic-admonition" title="Permalink to this headline"></a></h3>
<p>The generic <a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions">admonition</a> needs a title:</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">admonition</span><span class="p">::</span> generic admonition title
lorem ipsum ..
</pre></div>
</div>
<div class="admonition-generic-admonition-title admonition">
<p class="admonition-title">generic admonition title</p>
<p>lorem ipsum ..</p>
</div>
</div>
<div class="section" id="specific-admonitions">
<h3><a class="toc-backref" href="#id43">Specific admonitions</a><a class="headerlink" href="#specific-admonitions" title="Permalink to this headline"></a></h3>
<p>Specific admonitions: <a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/directives.html#hint">hint</a>, <a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/directives.html#note">note</a>, <a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/directives.html#tip">tip</a> <a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/directives.html#attention">attention</a>,
<a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/directives.html#caution">caution</a>, <a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/directives.html#danger">danger</a>, <a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/directives.html#error">error</a>, , <a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/directives.html#important">important</a>, and
<a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/directives.html#warning">warning</a> .</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">hint</span><span class="p">::</span>
lorem ipsum ..
<span class="p">..</span> <span class="ow">note</span><span class="p">::</span>
lorem ipsum ..
<span class="p">..</span> <span class="ow">warning</span><span class="p">::</span>
lorem ipsum ..
</pre></div>
</div>
<div class="admonition hint">
<p class="admonition-title">Hint</p>
<p>lorem ipsum ..</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>lorem ipsum ..</p>
</div>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>lorem ipsum ..</p>
</div>
<div class="admonition attention">
<p class="admonition-title">Attention</p>
<p>lorem ipsum ..</p>
</div>
<div class="admonition caution">
<p class="admonition-title">Caution</p>
<p>lorem ipsum ..</p>
</div>
<div class="admonition danger">
<p class="admonition-title">Danger</p>
<p>lorem ipsum ..</p>
</div>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>lorem ipsum ..</p>
</div>
<div class="admonition error">
<p class="admonition-title">Error</p>
<p>lorem ipsum ..</p>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>lorem ipsum ..</p>
</div>
</div>
</div>
<div class="section" id="tables">
<h2><a class="toc-backref" href="#id44">Tables</a><a class="headerlink" href="#tables" title="Permalink to this headline"></a></h2>
<div class="sidebar">
<p class="sidebar-title">Nested tables</p>
<p>Nested tables are ugly! Not all builder support nested tables, dont use
them!</p>
</div>
<p>ASCII-art tables like <a class="reference internal" href="#rest-simple-table"><span class="std std-ref">Simple tables</span></a> and <a class="reference internal" href="#rest-grid-table"><span class="std std-ref">Grid tables</span></a> might
be comfortable for readers of the text-files, but they have huge disadvantages
in the creation and modifying. First, they are hard to edit. Think about
adding a row or a column to a ASCII-art table or adding a paragraph in a cell,
it is a nightmare on big tables.</p>
<div class="sidebar">
<p class="sidebar-title">List tables</p>
<p>For meaningful patch and diff use <a class="reference internal" href="#rest-flat-table"><span class="std std-ref">flat-table</span></a>.</p>
</div>
<p>Second the diff of modifying ASCII-art tables is not meaningful, e.g. widening a
cell generates a diff in which also changes are included, which are only
ascribable to the ASCII-art. Anyway, if you prefer ASCII-art for any reason,
here are some helpers:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://www.emacswiki.org/emacs/TableMode">Emacs Table Mode</a></p></li>
<li><p><a class="reference external" href="https://www.tablesgenerator.com/text_tables">Online Tables Generator</a></p></li>
</ul>
<div class="section" id="simple-tables">
<span id="rest-simple-table"></span><h3><a class="toc-backref" href="#id45">Simple tables</a><a class="headerlink" href="#simple-tables" title="Permalink to this headline"></a></h3>
<p><a class="reference external" href="https://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 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">table::</span>
<span class="pre">directive</span></code> <a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/directives.html#table">(ref)</a> in front and place the table in its body:</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">table</span><span class="p">::</span> foo gate truth table
<span class="nc">:widths:</span> grid
<span class="nc">:align:</span> left
====== ====== ======
Inputs Output
------------- ------
A B A or B
====== ====== ======
False
--------------------
True
--------------------
True False True
(foo)
------ ------ ------
False True
(foo)
====== =============
</pre></div>
</div>
<div class="rst-example admonition">
<p class="admonition-title">Simple ASCII table</p>
<table class="colwidths-given docutils align-left" id="id11">
<caption><span class="caption-number">Table 6 </span><span class="caption-text">foo gate truth table</span><a class="headerlink" href="#id11" title="Permalink to this table"></a></caption>
<colgroup>
<col style="width: 33%" />
<col style="width: 33%" />
<col style="width: 33%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="2"><p>Inputs</p></th>
<th class="head"><p>Output</p></th>
</tr>
<tr class="row-even"><th class="head"><p>A</p></th>
<th class="head"><p>B</p></th>
<th class="head"><p>A or B</p></th>
</tr>
</thead>
<tbody>
<tr class="row-odd"><td colspan="3"><p>False</p></td>
</tr>
<tr class="row-even"><td colspan="3"><p>True</p></td>
</tr>
<tr class="row-odd"><td><p>True</p></td>
<td><p>False
(foo)</p></td>
<td><p>True</p></td>
</tr>
<tr class="row-even"><td><p>False</p></td>
<td colspan="2"><p>True
(foo)</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="grid-tables">
<span id="rest-grid-table"></span><h3><a class="toc-backref" href="#id46">Grid tables</a><a class="headerlink" href="#grid-tables" title="Permalink to this headline"></a></h3>
<p><a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables">Grid tables</a> allow colspan <em>colspan</em> and <em>rowspan</em>:</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">table</span><span class="p">::</span> grid table example
<span class="nc">:widths:</span> 1 1 5
+------------+------------+-----------+
<span class="o">|</span> Header 1 | Header 2 | Header 3 |
+============+============+===========+
<span class="o">|</span> body row 1 | column 2 | column 3 |
+------------+------------+-----------+
<span class="o">|</span> body row 2 | Cells may span columns.|
+------------+------------+-----------+
<span class="o">|</span> body row 3 | Cells may | - Cells |
+------------+ span rows. | - contain |
<span class="o">|</span> body row 4 | | - blocks. |
+------------+------------+-----------+
</pre></div>
</div>
<div class="rst-example admonition">
<p class="admonition-title">ASCII grid table</p>
<table class="colwidths-given docutils align-default" id="id12">
<caption><span class="caption-number">Table 7 </span><span class="caption-text">grid table example</span><a class="headerlink" href="#id12" title="Permalink to this table"></a></caption>
<colgroup>
<col style="width: 14%" />
<col style="width: 14%" />
<col style="width: 71%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Header 1</p></th>
<th class="head"><p>Header 2</p></th>
<th class="head"><p>Header 3</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>body row 1</p></td>
<td><p>column 2</p></td>
<td><p>column 3</p></td>
</tr>
<tr class="row-odd"><td><p>body row 2</p></td>
<td colspan="2"><p>Cells may span columns.</p></td>
</tr>
<tr class="row-even"><td><p>body row 3</p></td>
<td rowspan="2"><p>Cells may
span rows.</p></td>
<td rowspan="2"><ul class="simple">
<li><p>Cells</p></li>
<li><p>contain</p></li>
<li><p>blocks.</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p>body row 4</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="flat-table">
<span id="rest-flat-table"></span><h3><a class="toc-backref" href="#id47">flat-table</a><a class="headerlink" href="#flat-table" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">flat-table</span></code> is a further developed variant of the <a class="reference external" href="https://return42.github.io/linuxdoc/linuxdoc-howto/table-markup.html#list-table-directives" title="(in LinuxDoc v20210324)"><span class="xref std std-ref">list tables</span></a>. It is a double-stage list similar to the
<a class="reference external" href="https://docutils.sourceforge.net/docs/ref/rst/directives.html#list-table">list-table</a> with some additional features:</p>
<dl class="simple">
<dt>column-span: <code class="docutils literal notranslate"><span class="pre">cspan</span></code></dt><dd><p>with the role <code class="docutils literal notranslate"><span class="pre">cspan</span></code> a cell can be extended through additional columns</p>
</dd>
<dt>row-span: <code class="docutils literal notranslate"><span class="pre">rspan</span></code></dt><dd><p>with the role <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">:fill-cells:</span></code> this behavior can changed
from <em>auto span</em> to <em>auto fill</em>, which automatically inserts (empty) cells
instead of spanning the last cell.</p>
</dd>
<dt>options:</dt><dd><dl class="field-list simple">
<dt class="field-odd">header-rows</dt>
<dd class="field-odd"><p>[int] count of header rows</p>
</dd>
<dt class="field-even">stub-columns</dt>
<dd class="field-even"><p>[int] count of stub columns</p>
</dd>
<dt class="field-odd">widths</dt>
<dd class="field-odd"><p>[[int] [int] … ] widths of columns</p>
</dd>
<dt class="field-even">fill-cells</dt>
<dd class="field-even"><p>instead of auto-span missing cells, insert missing cells</p>
</dd>
</dl>
</dd>
<dt>roles:</dt><dd><dl class="field-list simple">
<dt class="field-odd">cspan</dt>
<dd class="field-odd"><p>[int] additional columns (<em>morecols</em>)</p>
</dd>
<dt class="field-even">rspan</dt>
<dd class="field-even"><p>[int] additional rows (<em>morerows</em>)</p>
</dd>
</dl>
</dd>
</dl>
<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> ( <code class="docutils literal notranslate"><span class="pre">..</span></code> )
and <em>targets</em> (e.g. a ref to <a class="reference internal" href="#row-body-2"><span class="std std-ref">row 2 of tables body</span></a>).</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">flat-table</span><span class="p">::</span> <span class="s">``flat-table``</span> example
<span class="nc">:header-rows:</span> 2
<span class="nc">:stub-columns:</span> 1
<span class="nc">:widths:</span> 1 1 1 1 2
<span class="m">*</span> - <span class="na">:rspan:</span><span class="nv">`1`</span> head / stub
<span class="m">-</span> <span class="na">:cspan:</span><span class="nv">`3`</span> head 1.1-4
<span class="m">*</span> - head 2.1
<span class="m">-</span> head 2.2
<span class="m">-</span> head 2.3
<span class="m">-</span> head 2.4
<span class="m">*</span> .. row body 1 / this is a comment
<span class="m">-</span> row 1
<span class="m">-</span> <span class="na">:rspan:</span><span class="nv">`2`</span> cell 1-3.1
<span class="m">-</span> cell 1.2
<span class="m">-</span> cell 1.3
<span class="m">-</span> cell 1.4
<span class="m">*</span> .. Comments and targets are allowed on <span class="ge">*table-row*</span> stage.
<span class="p"> ..</span> <span class="nt">_`row body 2`:</span>
<span class="m">-</span> row 2
<span class="m">-</span> cell 2.2
<span class="m">-</span> <span class="na">:rspan:</span><span class="nv">`1`</span> <span class="na">:cspan:</span><span class="nv">`1`</span>
cell 2.3 with a span over
<span class="m">*</span> col 3-4 &amp;
<span class="m">*</span> row 2-3
<span class="m">*</span> - row 3
<span class="m">-</span> cell 3.2
<span class="m">*</span> - row 4
<span class="m">-</span> cell 4.1
<span class="m">-</span> cell 4.2
<span class="m">-</span> cell 4.3
<span class="m">-</span> cell 4.4
<span class="m">*</span> - row 5
<span class="m">-</span> cell 5.1 with automatic span to rigth end
<span class="m">*</span> - row 6
<span class="m">-</span> cell 6.1
<span class="m">-</span> ..
</pre></div>
</div>
<div class="rst-example admonition">
<p class="admonition-title">List table</p>
<table class="docutils align-default" id="id13">
<caption><span class="caption-number">Table 8 </span><span class="caption-text"><code class="docutils literal notranslate"><span class="pre">flat-table</span></code> example</span><a class="headerlink" href="#id13" title="Permalink to this table"></a></caption>
<colgroup>
<col style="width: 17%" />
<col style="width: 17%" />
<col style="width: 17%" />
<col style="width: 17%" />
<col style="width: 33%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head stub" rowspan="2"><p> head / stub</p></th>
<th class="head" colspan="4"><p> head 1.1-4</p></th>
</tr>
<tr class="row-even"><th class="head stub"><p>head 2.1</p></th>
<th class="head"><p>head 2.2</p></th>
<th class="head"><p>head 2.3</p></th>
<th class="head"><p>head 2.4</p></th>
</tr>
</thead>
<tbody>
<tr class="row-odd"><th class="stub"><p>row 1</p></th>
<td rowspan="3"><p> cell 1-3.1</p></td>
<td><p>cell 1.2</p></td>
<td><p>cell 1.3</p></td>
<td><p>cell 1.4</p></td>
</tr>
<tr class="row-even"><th class="stub"><p>row 2</p>
</th>
<td><p>cell 2.2</p>
</td>
<td colspan="2" rowspan="2"><p id="row-body-2">
cell 2.3 with a span over</p>
<ul class="simple">
<li><p>col 3-4 &amp;</p></li>
<li><p>row 2-3</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><th class="stub"><p>row 3</p></th>
<td><p>cell 3.2</p></td>
</tr>
<tr class="row-even"><th class="stub"><p>row 4</p></th>
<td><p>cell 4.1</p></td>
<td><p>cell 4.2</p></td>
<td><p>cell 4.3</p></td>
<td><p>cell 4.4</p></td>
</tr>
<tr class="row-odd"><th class="stub"><p>row 5</p></th>
<td colspan="4"><p>cell 5.1 with automatic span to rigth end</p></td>
</tr>
<tr class="row-even"><th class="stub"><p>row 6</p></th>
<td><p>cell 6.1</p></td>
<td colspan="3"></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="csv-table">
<h3><a class="toc-backref" href="#id48">CSV table</a><a class="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>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">csv-table</span><span class="p">::</span> CSV table example
<span class="nc">:header:</span> .. , Column 1, Column 2
<span class="nc">:widths:</span> 2 5 5
<span class="nc">:stub-columns:</span> 1
<span class="nc">:file:</span> csv_table.txt
</pre></div>
</div>
<p>Content of file <code class="docutils literal notranslate"><span class="pre">csv_table.txt</span></code>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>stub col row 1, column, &quot;loremLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
voluptua.&quot;
stub col row 1, &quot;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.&quot;, column
stub col row 1, column, column
</pre></div>
</div>
<div class="rst-example admonition">
<p class="admonition-title">CSV table</p>
<table class="colwidths-given docutils align-default" id="id14">
<caption><span class="caption-number">Table 9 </span><span class="caption-text">CSV table example</span><a class="headerlink" href="#id14" title="Permalink to this table"></a></caption>
<colgroup>
<col style="width: 23%" />
<col style="width: 38%" />
<col style="width: 38%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head stub"></th>
<th class="head"><p>Column 1</p></th>
<th class="head"><p>Column 2</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><th class="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>
<tr class="row-odd"><th class="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>
<tr class="row-even"><th class="stub"><p>stub col row 1</p></th>
<td><p>column</p></td>
<td><p>column</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="section" id="templating">
<h2><a class="toc-backref" href="#id49">Templating</a><a class="headerlink" href="#templating" title="Permalink to this headline"></a></h2>
<div class="sidebar">
<p class="sidebar-title">Build environment</p>
<p>All <em>generic-doc</em> tasks are running in the <a class="reference internal" href="makefile.html#make-install"><span class="std std-ref">Python environment</span></a>.</p>
</div>
<p>Templating is suitable for documentation which is created generic at the build
time. The <a class="reference external" href="https://github.com/tardyp/sphinx-jinja">sphinx-jinja</a> extension evaluates <a class="reference external" href="https://jinja.palletsprojects.com/">jinja</a> templates in the <a class="reference internal" href="makefile.html#make-install"><span class="std std-ref">Python environment</span></a> (with searx modules installed). We use this e.g. to build chapter:
<a class="reference internal" href="../admin/engines.html#engines-generic"><span class="std std-ref">General Engine Settings</span></a>. Below the jinja directive from the
<a class="reference external" href="https://github.com/searx/searx/blob/master/docs/admin/engines.rst">git://docs/admin/engines.rst</a> is shown:</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">jinja</span><span class="p">::</span> searx
<span class="p"> ..</span> <span class="ow">flat-table</span><span class="p">::</span> Engines configured at built time (defaults)
<span class="nc">:header-rows:</span> 1
<span class="nc">:stub-columns:</span> 2
<span class="m">*</span> - Name (cfg)
<span class="m">-</span> S
<span class="m">-</span> Engine
<span class="m">-</span> TO
<span class="m">-</span> Categories
<span class="m">-</span> P
<span class="m">-</span> L
<span class="m">-</span> SS
<span class="m">-</span> D
<span class="m">-</span> TR
<span class="m">-</span> ET
<span class="m">-</span> W
<span class="m">-</span> D
<span class="m">-</span> DE
{% for name, mod in engines.items() %}
<span class="m">*</span> - {{name}}
<span class="m">-</span> !{{mod.shortcut}}
<span class="m">-</span> {{mod.__name__}}
<span class="m">-</span> {{mod.timeout}}
<span class="m">-</span> {{&quot;, &quot;.join(mod.categories)}}
<span class="m">-</span> {{(mod.paging and &quot;y&quot;) or &quot;&quot;}}
<span class="m">-</span> {{(mod.language_support and &quot;y&quot;) or &quot;&quot;}}
<span class="m">-</span> {{(mod.safesearch and &quot;y&quot;) or &quot;&quot;}}
<span class="m">-</span> {{(mod.disabled and &quot;y&quot;) or &quot;&quot;}}
<span class="m">-</span> {{(mod.time_range_support and &quot;y&quot;) or &quot;&quot;}}
<span class="m">-</span> {{mod.engine_type or &quot;&quot;}}
<span class="m">-</span> {{mod.weight or 1 }}
<span class="m">-</span> {{(mod.disabled and &quot;y&quot;) or &quot;&quot;}}
<span class="m">-</span> {{(mod.display_error_messages and &quot;y&quot;) or &quot;&quot;}}
{% endfor %}
</pre></div>
</div>
<p>The context for the template is selected in the line <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">jinja::</span> <span class="pre">searx</span></code>. In
sphinxs build configuration (<a class="reference external" href="https://github.com/searx/searx/blob/master/docs/conf.py">git://docs/conf.py</a>) the <code class="docutils literal notranslate"><span class="pre">searx</span></code> context
contains the <code class="docutils literal notranslate"><span class="pre">engines</span></code> and <code class="docutils literal notranslate"><span class="pre">plugins</span></code>.</p>
<div class="highlight-py notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">searx.search</span>
<span class="kn">import</span> <span class="nn">searx.engines</span>
<span class="kn">import</span> <span class="nn">searx.plugins</span>
<span class="n">searx</span><span class="o">.</span><span class="n">search</span><span class="o">.</span><span class="n">initialize</span><span class="p">()</span>
<span class="n">jinja_contexts</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">&#39;searx&#39;</span><span class="p">:</span> <span class="p">{</span>
<span class="s1">&#39;engines&#39;</span><span class="p">:</span> <span class="n">searx</span><span class="o">.</span><span class="n">engines</span><span class="o">.</span><span class="n">engines</span><span class="p">,</span>
<span class="s1">&#39;plugins&#39;</span><span class="p">:</span> <span class="n">searx</span><span class="o">.</span><span class="n">plugins</span><span class="o">.</span><span class="n">plugins</span>
<span class="p">},</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="tabbed-views">
<h2><a class="toc-backref" href="#id50">Tabbed views</a><a class="headerlink" href="#tabbed-views" title="Permalink to this headline"></a></h2>
<p>With <a class="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 <a class="reference external" href="https://github.com/djungelorm/sphinx-tabs#group-tabs">group-tabs</a> directive,
others are <a class="reference external" href="https://github.com/djungelorm/sphinx-tabs#basic-tabs">basic-tabs</a> and <a class="reference external" href="https://github.com/djungelorm/sphinx-tabs#code-tabs">code-tabs</a>. Below a <em>group-tab</em> example from
<a class="reference internal" href="../admin/buildhosts.html#docs-build"><span class="std std-ref">Build docs</span></a> is shown:</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">tabs</span><span class="p">::</span>
<span class="p"> ..</span> <span class="ow">group-tab</span><span class="p">::</span> Ubuntu / debian
<span class="p"> ..</span> <span class="ow">code-block</span><span class="p">::</span> <span class="k">sh</span>
$ sudo apt install shellcheck
<span class="p"> ..</span> <span class="ow">group-tab</span><span class="p">::</span> Arch Linux
<span class="p"> ..</span> <span class="ow">code-block</span><span class="p">::</span> <span class="k">sh</span>
$ sudo pacman -S shellcheck
<span class="p"> ..</span> <span class="ow">group-tab</span><span class="p">::</span> Fedora / RHEL
<span class="p"> ..</span> <span class="ow">code-block</span><span class="p">::</span> sh
$ sudo dnf install ShellCheck
</pre></div>
</div>
</div>
<div class="section" id="math-equations">
<span id="math"></span><h2><a class="toc-backref" href="#id51">Math equations</a><a class="headerlink" href="#math-equations" title="Permalink to this headline"></a></h2>
<div class="sidebar">
<p class="sidebar-title">About LaTeX</p>
<ul class="simple">
<li><p><a class="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>
<li><p><a class="reference external" href="https://en.wikibooks.org/wiki/LaTeX/Mathematics">Mathematics</a></p></li>
<li><p><a class="reference internal" href="../admin/buildhosts.html#docs-build"><span class="std std-ref">Build docs</span></a></p></li>
</ul>
</div>
<p>The input language for mathematics is LaTeX markup using the <a class="reference external" href="https://ctan.org/pkg/amsmath">CTAN: amsmath</a>
package.</p>
<p>To embed LaTeX markup in reST documents, use role <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-math" title="(in Sphinx v6.0.0)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">:math:</span></code></a> for
inline and directive <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-math" title="(in Sphinx v6.0.0)"><code class="xref rst rst-dir docutils literal notranslate"><span class="pre">..</span> <span class="pre">math::</span></code></a> for block markup.</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span>In <span class="na">:math:numref:</span><span class="nv">`schroedinger general`</span> the time-dependent Schrödinger equation
is shown.
<span class="p">..</span> <span class="ow">math</span><span class="p">::</span>
<span class="nc">:label:</span> schroedinger general
\mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
\hat{H} |\,\psi (t) \rangle.
</pre></div>
</div>
<div class="rst-example admonition">
<p class="admonition-title">LaTeX math equation</p>
<p>In <a class="reference internal" href="#equation-schroedinger-general">(1)</a> the time-dependent Schrödinger equation
is shown.</p>
<div class="math" id="equation-schroedinger-general">
<p><span class="eqno">(1)<a class="headerlink" href="#equation-schroedinger-general" title="Permalink to this equation"></a></span><img src="../_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 <code class="docutils literal notranslate"><span class="pre">\tfrac</span></code> (<em>textstyle</em>) and <code class="docutils literal notranslate"><span class="pre">\dfrac</span></code>
(<em>displaystyle</em>) used in a inline markup or another fraction.</p>
<div class="highlight-reST notranslate"><div class="highlight"><pre><span></span><span class="s">``\tfrac``</span> <span class="gs">**inline example**</span> <span class="na">:math:</span><span class="nv">`\tfrac{\tfrac{1}{x}+\tfrac{1}{y}}{y-z}`</span>
<span class="s">``\dfrac``</span> <span class="gs">**inline example**</span> <span class="na">:math:</span><span class="nv">`\dfrac{\dfrac{1}{x}+\dfrac{1}{y}}{y-z}`</span>
</pre></div>
</div>
<div class="rst-example admonition">
<p class="admonition-title">Line spacing</p>
<p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
voluptua. …
<code class="docutils literal notranslate"><span class="pre">\tfrac</span></code> <strong>inline example</strong> <img class="math" src="../_images/math/3b8127a8eed95247f9249ea6c85e8e86df1baa82.svg" alt="\tfrac{\tfrac{1}{x}+\tfrac{1}{y}}{y-z}"/>
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>
<p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
voluptua. …
<code class="docutils literal notranslate"><span class="pre">\tfrac</span></code> <strong>inline example</strong> <img class="math" src="../_images/math/07c9ff4251510b06013159f4e45ec9ab97044096.svg" alt="\dfrac{\dfrac{1}{x}+\dfrac{1}{y}}{y-z}"/>
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>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<span id="sidebar-top"></span>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/searx_logo_small.png" alt="Logo"/>
</a></p>
<h3>Project Links</h3>
<ul>
<li><a href="blog/index.html">Blog</a>
<li><a href="https://github.com/searx/searx">Source</a>
<li><a href="https://github.com/searx/searx/wiki">Wiki</a>
<li><a href="https://searx.space">Public instances</a>
<li><a href="https://twitter.com/Searx_engine">Twitter</a>
<li><a href="https://github.com/searx/searx/issues">Issue Tracker</a>
</ul><h3>Navigation</h3>
<ul>
<li><a href="../index.html">Overview</a>
<ul>
<li><a href="index.html">Developer documentation</a>
<ul>
<li>Previous: <a href="makefile.html" title="previous chapter">Makefile</a>
<li>Next: <a href="../searx_extra/index.html" title="next chapter">Tooling box <code class="docutils literal notranslate"><span class="pre">searx_extra</span></code> for developers and users</a></ul>
</li>
</ul>
</li>
</ul>
<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>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2015-2021, Adam Tauber, Noémi Ványi.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.4.0.
</div>
<script src="../_static/version_warning_offset.js"></script>
</body>
</html>