docs(dev): add more markups to reST primer

- Literal blocks
- Unicode substitution
- Horizontal list
- Math equations

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

docs/conf.py

@@ -49,6 +49,8 @@ extlinks['durole'] = (
     'http://docutils.sourceforge.net/docs/ref/rst/roles.html#%s', '')
 extlinks['dudir'] =  (
     'http://docutils.sourceforge.net/docs/ref/rst/directives.html#%s', '')
+extlinks['ctan'] =  (
+    'https://ctan.org/pkg/%s', 'CTAN: ')
 
 extensions = [
     'sphinx.ext.extlinks',

docs/dev/reST.rst

@@ -11,10 +11,12 @@ reST primer
 
 We at searx are using reStructuredText (aka reST_) markup for all kind of
 documentation, with the builders from the Sphinx_ project a HTML output is
-generated and deployed at :docs:`github.io <.>`.
+generated and deployed at :docs:`github.io <.>`.  For build prerequisites read
+:ref:`docs build`.
 
-The sources of Searx's documentation are located at :origin:`docs`.  Run
-:ref:`make docs-live <make docs-live>` to build HTML while editing.
+The source files of Searx's documentation are located at :origin:`docs`.  Sphinx
+assumes source files to be encoded in UTF-8 by defaul.  Run :ref:`make docs-live
+<make docs-live>` to build HTML while editing.
 
 .. sidebar:: Further reading
 
@@ -318,6 +320,123 @@ To list all anchors of the inventory (e.g. ``python``) use:
 
    $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
 
+Literal blocks
+==============
+
+The simplest form of :duref:`literal-blocks` is a indented block introduced by
+two colons (``::``).  For highlighting use :dudir:`highlight` or :ref:`reST
+code` directive.  To include literals from external files use directive
+:dudir:`literalinclude`.
+
+.. _reST literal:
+
+``::``
+------
+
+.. code:: reST
+
+   ::
+
+     Literal block
+
+   Lorem ipsum dolor::
+
+     Literal block
+
+   Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
+   eirmod tempor invidunt ut labore ::
+
+     Literal block
+
+.. admonition:: Literal block
+   :class: rst-example
+
+   ::
+
+     Literal block
+
+   Lorem ipsum dolor::
+
+     Literal block
+
+   Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
+   eirmod tempor invidunt ut labore ::
+
+     Literal block
+
+
+.. _reST code:
+
+``code-block``
+--------------
+
+.. _pygments: https://pygments.org/languages/
+
+.. sidebar:: Syntax highlighting
+
+   is handled by pygments_.
+
+The :rst:dir:`code-block` directive is a variant of the :dudir:`code` directive
+with additional options.  To learn more about code literals visit
+:ref:`sphinx:code-examples`.
+
+.. code-block:: reST
+
+   The URL ``/stats`` handle is shown in :ref:`stats-handle`
+
+   .. code-block:: Python
+      :caption: python code block
+      :name: stats-handle
+
+      @app.route('/stats', methods=['GET'])
+      def stats():
+          """Render engine statistics page."""
+          stats = get_engines_stats()
+          return render(
+              'stats.html'
+              , stats = stats )
+
+.. code-block:: reST
+
+.. admonition:: Code block
+   :class: rst-example
+
+   The URL ``/stats`` handle is shown in :ref:`stats-handle`
+
+   .. code-block:: Python
+      :caption: python code block
+      :name: stats-handle
+
+      @app.route('/stats', methods=['GET'])
+      def stats():
+          """Render engine statistics page."""
+          stats = get_engines_stats()
+          return render(
+              'stats.html'
+              , stats = stats )
+
+Unicode substitution
+====================
+
+The :dudir:`unicode directive <unicode-character-codes>` converts Unicode
+character codes (numerical values) to characters.  This directive can only be
+used within a substitution definition.
+
+.. code-block:: reST
+
+   .. |copy| unicode:: 0xA9 .. copyright sign
+   .. |(TM)| unicode:: U+2122
+
+   Trademark |(TM)| and copyright |copy| glyphs.
+
+.. admonition:: Unicode
+   :class: rst-example
+
+   .. |copy| unicode:: 0xA9 .. copyright sign
+   .. |(TM)| unicode:: U+2122
+
+   Trademark |(TM)| and copyright |copy| glyphs.
+
 
 .. _reST roles:
 
@@ -351,7 +470,7 @@ The general markup is one of:
    :rst:role:`kbd`            :kbd:`C-x C-f`                     ``:kbd:`C-x C-f```
    :rst:role:`menuselection`  :menuselection:`Open --> File`     ``:menuselection:`Open --> File```
    :rst:role:`download`       :download:`this file <reST.rst>`   ``:download:`this file <reST.rst>```
-   :rst:role:`math`           :math:`a^2 + b^2 = c^2`            ``:math:`a^2 + b^2 = c^2```
+   math_                      :math:`a^2 + b^2 = c^2`            ``:math:`a^2 + b^2 = c^2```
    :rst:role:`ref`            :ref:`svg image example`           ``:ref:`svg image example```
    :rst:role:`command`        :command:`ls -la`                  ``:command:`ls -la```
    :durole:`emphasis`         :emphasis:`italic`                 ``:emphasis:`italic```
@@ -371,16 +490,17 @@ Figures & Images
    is flexible.  To get best results in the generated output format, install
    ImageMagick_ and Graphviz_.
 
-Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`.  Scalable here means;
-scalable in sense of the build process.  Normally in absence of a converter
+Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`.  Scaleable here means;
+scaleable in sense of the build process.  Normally in absence of a converter
 tool, the build process will break.  From the authors POV it’s annoying to care
 about the build process when handling with images, especially since he has no
 access to the build process.  With :ref:`linuxdoc:kfigure` the build process
 continues and scales output quality in dependence of installed image processors.
 
-If you want to add an image, you should use the ``kernel-figure`` and
-``kernel-image`` directives.  E.g. to insert a figure with a scalable image
-format use SVG (:ref:`svg image example`):
+If you want to add an image, you should use the ``kernel-figure`` (inheritance
+of :dudir:`figure`) and ``kernel-image`` (inheritance of :dudir:`image`)
+directives.  E.g. to insert a figure with a scaleable image format use SVG
+(:ref:`svg image example`):
 
 .. code:: reST
 
@@ -389,7 +509,7 @@ format use SVG (:ref:`svg image example`):
    .. kernel-figure:: svg_image.svg
       :alt: SVG image example
 
-      simple SVG image
+      Simple SVG image
 
     To refer the figure, a caption block is needed: :ref:`svg image example`.
 
@@ -398,7 +518,7 @@ format use SVG (:ref:`svg image example`):
 .. kernel-figure:: svg_image.svg
    :alt: SVG image example
 
-   simple SVG image
+   Simple SVG image.
 
 To refer the figure, a caption block is needed: :ref:`svg image example`.
 
@@ -571,6 +691,35 @@ List markup (:duref:`ref <bullet-lists>`) is simple:
    #. It has two items too.
 
 
+Horizontal list
+---------------
+
+The :rst:dir:`.. hlist:: <hlist>` transforms a bullet list into a more compact
+list.
+
+.. code:: reST
+
+   .. hlist::
+
+      - first list item
+      - second list item
+      - third list item
+      ...
+
+.. admonition:: hlist
+   :class: rst-example
+
+   .. hlist::
+
+      - first list item
+      - second list item
+      - third list item
+      - next list item
+      - next list item xxxx
+      - next list item yyyy
+      - next list item zzzz
+
+
 Definition list
 ---------------
 
@@ -1158,70 +1307,84 @@ Tabbed views
 
 With `sphinx-tabs`_ extension we have *tabbed views*.  To provide installation
 instructions with one tab per distribution we use the `group-tabs`_ directive,
-others are basic-tabs_ and code-tabs_.
-
-
-.. code:: reST
-
-   .. tabs::
-
-      .. group-tab:: Linux
+others are basic-tabs_ and code-tabs_.  Below a *group-tab* example from
+:ref:`docs build` is shown:
 
-         Linux Line 1
+.. literalinclude:: ../admin/buildhosts.rst
+   :language: reST
+   :start-after: .. _system requirements:
+   :end-before: .. _system requirements END:
 
-      .. group-tab:: Mac OSX
 
-         Mac OSX Line 1
+.. _math:
 
-      .. group-tab:: Windows
+Math equations
+==============
 
-         Windows Line 1
+.. _Mathematics: https://en.wikibooks.org/wiki/LaTeX/Mathematics
+.. _amsmath user guide:
+   http://vesta.informatik.rwth-aachen.de/ftp/pub/mirror/ctan/macros/latex/required/amsmath/amsldoc.pdf
 
-   .. tabs::
+.. sidebar:: About LaTeX
 
-      .. group-tab:: Linux
+   - `amsmath user guide`_
+   - Mathematics_
+   - :ref:`docs build`
 
-         Linux Line 1
+The input language for mathematics is LaTeX markup using the :ctan:`amsmath`
+package.
 
-      .. group-tab:: Mac OSX
+To embed LaTeX markup in reST documents, use role :rst:role:`:math: <math>` for
+inline and directive :rst:dir:`.. math:: <math>` for block markup.
 
-         Mac OSX Line 1
+.. code:: reST
 
-      .. group-tab:: Windows
+   In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
+   is shown.
 
-         Windows Line 1
+   .. math::
+      :label: schroedinger general
 
+       \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
+             \hat{H} |\,\psi (t) \rangle.
 
-.. admonition:: Tabbed view (grouped)
+.. admonition:: LaTeX math equation
    :class: rst-example
 
-   .. tabs::
-
-      .. group-tab:: Linux
-
-         Linux Line 1
-
-      .. group-tab:: Mac OSX
+   In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
+   is shown.
 
-         Mac OSX Line 1
+   .. math::
+      :label: schroedinger general
 
-      .. group-tab:: Windows
+       \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
+             \hat{H} |\,\psi (t) \rangle.
 
-         Windows Line 1
 
-   .. tabs::
+The next example shows the difference of ``\tfrac`` (*textstyle*) and ``\dfrac``
+(*displaystyle*) used in a inline markup or another fraction.
 
-      .. group-tab:: Linux
-
-         Linux Line 1
-
-      .. group-tab:: Mac OSX
+.. code:: reST
 
-         Mac OSX Line 1
+   ``\tfrac`` **inline example** :math:`\tfrac{\tfrac{1}{x}+\tfrac{1}{y}}{y-z}`
+   ``\dfrac`` **inline example** :math:`\dfrac{\dfrac{1}{x}+\dfrac{1}{y}}{y-z}`
 
-      .. group-tab:: Windows
+.. admonition:: Line spacing
+   :class: rst-example
 
-         Windows Line 1
+   Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
+   eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
+   voluptua.  ...
+   ``\tfrac`` **inline example** :math:`\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.
+
+   Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
+   eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
+   voluptua.  ...
+   ``\tfrac`` **inline example** :math:`\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.
 
 
 .. _KISS: https://en.wikipedia.org/wiki/KISS_principle