doc: add content to reST primer (WIP) // linuxdoc

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

1 files changed, 222 insertions, 91 deletions

diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst
index c8482e77d..5522f9e15 100644
--- a/docs/dev/reST.rst
+++ b/docs/dev/reST.rst
@@ -18,11 +18,26 @@ The sources of Searx's documentation are located at :origin:`docs`.  Run
 
 ------
 
+.. sidebar:: Further reading
+
+   - Sphinx-Primer_
+   - `Sphinx markup constructs`_
+   - reST_, docutils_, `docutils FAQ`_
+   - Sphinx_, `sphinx-doc FAQ`_
+   - `sphinx config`_, doctree_
+   - `sphinx cross references`_
+   - linuxdoc_
+   - intersphinx_
+   - `Sphinx's autodoc`_
+   - `Sphinx's Python domain`_, `Sphinx's C domain`_
+
 .. contents:: Contents
    :depth: 3
    :local:
    :backlinks: entry
 
+------
+
 Sphinx_ and reST_ have their place in the python ecosystem.  Over that reST is
 used in popular projects, e.g the Linux kernel documentation `[kernel doc]`_.
 
@@ -55,18 +70,6 @@ To be more concrete what a *point of view* means.  In the (:origin:`docs`)
 folder we have three sections (and the *blog* folder), each dedicate to a
 different group of audience.
 
-.. sidebar:: Further reading
-
-   - Sphinx-Primer_
-   - `Sphinx markup constructs`_
-   - reST_, docutils_, `docutils FAQ`_
-   - Sphinx_, `sphinx-doc FAQ`_
-   - `sphinx config`_, doctree_
-   - `sphinx cross references`_
-   - intersphinx_
-   - `Sphinx's autodoc`_
-   - `Sphinx's Python domain`_, `Sphinx's C domain`_
-
 User's POV: :origin:`docs/user`
   A typical user knows about search engines and might have heard about
   meta crawlers and privacy.
@@ -100,25 +103,52 @@ Basic inline markup
   inline markup delimiters, they have to be escaped with a backslash (``\*foo is
   a pointer``).
 
+.. _reST basic structure:
 
-Roles
-=====
+Basic article structure
+=======================
 
-A *custom interpreted text role* (:duref:`ref <roles>`) is an inline piece of
-explicit markup.  It signifies that that the enclosed text should be interpreted
-in a specific way.  The general syntax is ``:rolename:`content```.
+The basic structure of an article makes use of heading adornments to markup
+chapter, sections and subsections.
+
+#. ``=`` with overline for document title
+#. ``=`` for chapters
+#. ``-`` for sections
+#. ``~`` for subsections
+
+.. _reST template:
+
+.. admonition:: reST template
+   :class: rst-example
 
-Docutils supports the following roles:
+   .. code:: reST
 
-* :durole:`emphasis` -- equivalent of ``*emphasis*``
-* :durole:`strong` -- equivalent of ``**strong**``
-* :durole:`literal` -- equivalent of ````literal````
-* :durole:`subscript` -- subscript text
-* :durole:`superscript` -- superscript text
-* :durole:`title-reference` -- for titles of books, periodicals, and other
-  materials
+       .. _document title:
 
-Refer to `Sphinx Roles`_ for roles added by Sphinx.
+       ==============
+       Document title
+       ==============
+
+       Lorem ipsum dolor sit amet, consectetur adipisici elit ..
+       Further read :ref:`chapter title`.
+
+       .. _chapter title:
+
+       Chapters
+       ========
+
+       Ut enim ad minim veniam, quis nostrud exercitation ullamco
+       laboris nisi ut aliquid ex ea commodi consequat ...
+
+       Section
+       -------
+
+       lorem ..
+
+       Subsection
+       ~~~~~~~~~~
+
+       lorem ..
 
 
 Anchors & Links
@@ -196,42 +226,29 @@ smart references
 ----------------
 
 With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
-content becomes smart. To refer ...
-
-sphinx.ext.extlinks_:
-
-:project's wiki article:          :wiki:`Searx-instances`
-:to docs public URL:              :docs:`dev/reST.html`
-:files & folders from origin:     :origin:`docs/dev/reST.rst`
-:a pull request:                  :pull:`1756`
-:a patch:                         :patch:`af2cae6`
-:a PyPi package:                  :pypi:`searx`
-:a manual page man:               :man:`bash`
-
-.. code:: reST
-
-   :project's wiki article:          :wiki:`Searx-instances`
-   :to docs public URL:              :docs:`dev/reST.html`
-   :files & folders from origin:     :origin:`docs/dev/reST.rst`
-   :a pull request:                  :pull:`1756`
-   :a patch:                         :patch:`af2cae6`
-   :a PyPi package:                  :pypi:`searx`
-   :a manual page man:               :man:`bash`
-
-
-intersphinx_:
-
-   :external anchor:                 :ref:`python:and`
-   :external doc anchor:             :doc:`jinja:templates`
-   :python code object:              :py:obj:`datetime.datetime`
-   :flask code object:               webapp is a :py:obj:`flask.Flask` app
-
-.. code:: reST
-
-   :external anchor:                 :ref:`python:and`
-   :external doc anchor:             :doc:`jinja:templates`
-   :python code object:              :py:obj:`datetime.datetime`
-   :flask code object:               webapp is a :py:obj:`flask.Flask` app
+content becomes smart.
+
+========================== ================================== ====================================
+refer ...                  rendered example                   markup
+========================== ================================== ====================================
+:rst:role:`rfc`            :rfc:`822`                         ``:rfc:`822```
+:rst:role:`pep`            :pep:`8`                           ``:pep:`8```
+sphinx.ext.extlinks_
+--------------------------------------------------------------------------------------------------
+project's wiki article     :wiki:`Searx-instances`            ``:wiki:`Searx-instances```
+to docs public URL         :docs:`dev/reST.html`              ``:docs:`dev/reST.html```
+files & folders origin     :origin:`docs/dev/reST.rst`        ``:origin:`docs/dev/reST.rst```
+pull request               :pull:`1756`                       ``:pull:`1756```
+patch                      :patch:`af2cae6`                   ``:patch:`af2cae6```
+PyPi package               :pypi:`searx`                      ``:pypi:`searx```
+manual page man            :man:`bash`                        ``:man:`bash```
+intersphinx_
+--------------------------------------------------------------------------------------------------
+external anchor            :ref:`python:and`                  ``:ref:`python:and```
+external doc anchor        :doc:`jinja:templates`             ``:doc:`jinja:templates```
+python code object         :py:obj:`datetime.datetime`        ``:py:obj:`datetime.datetime```
+flask code object          :py:obj:`flask.Flask`              ``:py:obj:`flask.Flask```
+========================== ================================== ====================================
 
 
 Intersphinx is configured in :origin:`docs/conf.py`:
@@ -242,6 +259,8 @@ Intersphinx is configured in :origin:`docs/conf.py`:
         "python": ("https://docs.python.org/3/", None),
         "flask": ("https://flask.palletsprojects.com/", None),
 	"jinja": ("https://jinja.palletsprojects.com/", None),
+        "linuxdoc" : ("https://return42.github.io/linuxdoc/", None),
+        "sphinx" : ("https://www.sphinx-doc.org/en/master/", None),
     }
 
 
@@ -252,52 +271,163 @@ To list all anchors of the inventory (e.g. ``python``) use:
    $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
 
 
-.. _reST basic structure:
+Roles
+=====
 
-Basic article structure
-=======================
+A *custom interpreted text role* (:duref:`ref <roles>`) is an inline piece of
+explicit markup.  It signifies that that the enclosed text should be interpreted
+in a specific way.  The general syntax is ``:rolename:`content```.
 
-The basic structure of an article makes use of heading adornments to markup
-chapter, sections and subsections.
+========================== ================================== ====================================
+role                       rendered example                   markup
+========================== ================================== ====================================
+:rst:role:`guilabel`       :guilabel:`&Cancel`                ``:guilabel:`&Cancel```
+: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```
+: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```
+:durole:`strong`           :strong:`bold`                     ``:strong:`bold```
+:durole:`literal`          :literal:`foo()`                   ``:literal:`foo()```
+:durole:`subscript`        H\ :sub:`2`\ O                     ``H\ :sub:`2`\ O``
+:durole:`superscript`      E = mc\ :sup:`2`                   ``E = mc\ :sup:`2```
+:durole:`title-reference`  :title:`Time`                      ``:title:`Time```
+========================== ================================== ====================================
 
-#. ``=`` with overline for document title
-#. ``=`` for chapters
-#. ``-`` for sections
-#. ``~`` for subsections
+Refer to `Sphinx Roles`_ for roles added by Sphinx.
 
-.. _reST template:
 
-.. admonition:: reST template
+Figures & Images
+================
+
+Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`.  Scalable here means;
+scalable in sense of the build process.  Normally in absence of a converter
+tool, the build process will break.  From the authors POV it’s annoying to care
+about the build process when handling with images, especially since he has no
+access to the build process.  With :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`):
+
+.. code:: reST
+
+   .. _svg image example:
+
+   .. kernel-figure:: svg_image.svg
+      :alt: simple SVG image
+
+      SVG image example
+
+.. _svg image example:
+
+.. kernel-figure:: svg_image.svg
+   :alt: simple SVG image
+
+   SVG image example
+
+DOT files (aka Graphviz)
+------------------------
+
+The kernel figure (and image) directive support **DOT** formated files, see
+
+* DOT: http://graphviz.org/pdf/dotguide.pdf
+* Graphviz: http://www.graphviz.org/content/dot-language
+
+A simple example (:ref:`hello_dot_file`):
+
+.. code:: reST
+
+   .. kernel-figure:: hello.dot
+      :alt: hello world
+
+      DOT's hello world example
+
+.. admonition:: hello.dot
    :class: rst-example
 
-   .. code:: reST
+   .. kernel-figure:: hello.dot
+      :alt: hello world
 
-       .. _document title:
+      DOT's hello world example
 
-       ==============
-       Document title
-       ==============
+``kernel-render`` DOT
+---------------------
 
-       Lorem ipsum dolor sit amet, consectetur adipisici elit ..
-       Further read :ref:`chapter title`.
+Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
+``kernel-render`` directives.
 
-       .. _chapter title:
+.. code:: reST
 
-       Chapters
-       ========
+   .. kernel-render:: DOT markup
+      :alt: foobar digraph
+      :caption: Embedded **DOT** (Graphviz) code
 
-       Ut enim ad minim veniam, quis nostrud exercitation ullamco
-       laboris nisi ut aliquid ex ea commodi consequat ...
+      digraph foo {
+        "bar" -> "baz";
+      }
 
-       Section
-       -------
+How this will be rendered depends on the installed tools.  If Graphviz is
+installed, you will see an vector image.  If not the raw markup is inserted as
+*literal-block* (:ref:`hello_dot_render`).
 
-       lorem ..
+.. admonition:: DOT markup
+   :class: rst-example
 
-       Subsection
-       ~~~~~~~~~~
+   .. _hello_dot_render:
+
+   .. kernel-render:: DOT
+      :alt: foobar digraph
+      :caption: Embedded **DOT** (Graphviz) code
+
+      digraph foo {
+        "bar" -> "baz";
+      }
+
+The *render* directive has all the options known from the *figure* directive,
+plus option ``caption``.  If ``caption`` has a value, a *figure* node is
+inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if
+you want to refer it (:ref:`hello_svg_render`).
+
+
+``kernel-render`` SVG
+---------------------
+
+.. code:: reST
+
+   .. kernel-render:: SVG markup
+      :caption: Embedded **SVG** markup
+      :alt: so-nw-arrow
+..
+
+   .. code:: xml
+
+      <?xml version="1.0" encoding="UTF-8"?>
+      <svg xmlns="http://www.w3.org/2000/svg"
+        version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
+      <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
+      <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
+      </svg>
+
+.. admonition:: SVG markup
+   :class: rst-example
+
+   .. _hello_svg_render:
+
+   .. kernel-render:: SVG
+      :caption: Embedded **SVG** markup
+      :alt: so-nw-arrow
+
+      <?xml version="1.0" encoding="UTF-8"?>
+      <svg xmlns="http://www.w3.org/2000/svg"
+        version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
+      <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
+      <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
+      </svg>
 
-       lorem ..
 
 .. _reST lists:
 
@@ -489,3 +619,4 @@ Further list blocks
     http://www.sphinx-doc.org/en/master/extdev/tutorial.html?highlight=doctree#build-phases
 .. _docutils: http://docutils.sourceforge.net/docs/index.html
 .. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html
+.. _linuxdoc: https://return42.github.io/linuxdoc