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

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

docs/_themes/searx/static/searx.css

@@ -29,6 +29,14 @@ p.sidebar-title, .sidebar p {
 }
 
 
+div.admonition,
+div.topic {
+  background-color: #fafafa;
+  margin: 8px 0px;
+  padding: 1em;
+  border: none;
+}
+
 /* admonitions with (rendered) reST markup examples (:class: rst-example)
  *
  * .. admonition:: title of the example

docs/conf.py

@@ -20,6 +20,7 @@ highlight_language = 'none'
 
 master_doc = "index"
 source_suffix = '.rst'
+numfig = True
 
 # usage::   lorem :patch:`f373169` ipsum
 extlinks = {}
@@ -35,6 +36,8 @@ extlinks['search'] = (SEARX_URL + '/%s', '#')
 extlinks['docs'] = (DOCS_URL + '/%s', 'docs: ')
 extlinks['pypi'] = ('https://pypi.org/project/%s', 'PyPi: ')
 extlinks['man'] = ('https://manpages.debian.org/jump?q=%s', '')
+#extlinks['role'] = (
+#    'https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-%s', '')
 extlinks['duref'] = (
     'http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#%s', '')
 extlinks['durole'] = (
@@ -49,6 +52,12 @@ extensions = [
     "sphinx.ext.intersphinx",
     "pallets_sphinx_themes",
     "sphinx_issues", # https://github.com/sloria/sphinx-issues/blob/master/README.rst
+    'linuxdoc.rstFlatTable',    # Implementation of the 'flat-table' reST-directive.
+    'linuxdoc.rstKernelDoc',    # Implementation of the 'kernel-doc' reST-directive.
+    'linuxdoc.kernel_include',  # Implementation of the 'kernel-include' reST-directive.
+    'linuxdoc.manKernelDoc',    # Implementation of the 'kernel-doc-man' builder
+    'linuxdoc.cdomain',         # Replacement for the sphinx c-domain.
+    'linuxdoc.kfigure',         # Sphinx extension which implements scalable image handling.
 ]
 
 intersphinx_mapping = {
@@ -56,6 +65,8 @@ intersphinx_mapping = {
     "flask": ("https://flask.palletsprojects.com/", None),
     # "werkzeug": ("https://werkzeug.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),
 }
 
 issues_github_path = "asciimoo/searx"

docs/dev/hello.dot

@@ -0,0 +1,3 @@
+graph G {
+      Hello -- World
+}

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
+The basic structure of an article makes use of heading adornments to markup
-explicit markup.  It signifies that that the enclosed text should be interpreted
+chapter, sections and subsections.
-in a specific way.  The general syntax is ``:rolename:`content```.
 
-Docutils supports the following roles:
+#. ``=`` with overline for document title
+#. ``=`` for chapters
+#. ``-`` for sections
+#. ``~`` for subsections
 
-* :durole:`emphasis` -- equivalent of ``*emphasis*``
+.. _reST template:
-* :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
 
-Refer to `Sphinx Roles`_ for roles added by Sphinx.
+.. admonition:: reST template
+   :class: rst-example
+
+   .. code:: reST
+
+       .. _document title:
+
+       ==============
+       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 ...
+content becomes smart.
 
-sphinx.ext.extlinks_:
+========================== ================================== ====================================
-
+refer ...                  rendered example                   markup
-:project's wiki article:          :wiki:`Searx-instances`
+========================== ================================== ====================================
-:to docs public URL:              :docs:`dev/reST.html`
+:rst:role:`rfc`            :rfc:`822`                         ``:rfc:`822```
-:files & folders from origin:     :origin:`docs/dev/reST.rst`
+:rst:role:`pep`            :pep:`8`                           ``:pep:`8```
-:a pull request:                  :pull:`1756`
+sphinx.ext.extlinks_
-:a patch:                         :patch:`af2cae6`
+--------------------------------------------------------------------------------------------------
-:a PyPi package:                  :pypi:`searx`
+project's wiki article     :wiki:`Searx-instances`            ``:wiki:`Searx-instances```
-:a manual page man:               :man:`bash`
+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```
-.. code:: reST
+pull request               :pull:`1756`                       ``:pull:`1756```
-
+patch                      :patch:`af2cae6`                   ``:patch:`af2cae6```
-   :project's wiki article:          :wiki:`Searx-instances`
+PyPi package               :pypi:`searx`                      ``:pypi:`searx```
-   :to docs public URL:              :docs:`dev/reST.html`
+manual page man            :man:`bash`                        ``:man:`bash```
-   :files & folders from origin:     :origin:`docs/dev/reST.rst`
+intersphinx_
-   :a pull request:                  :pull:`1756`
+--------------------------------------------------------------------------------------------------
-   :a patch:                         :patch:`af2cae6`
+external anchor            :ref:`python:and`                  ``:ref:`python:and```
-   :a PyPi package:                  :pypi:`searx`
+external doc anchor        :doc:`jinja:templates`             ``:doc:`jinja:templates```
-   :a manual page man:               :man:`bash`
+python code object         :py:obj:`datetime.datetime`        ``:py:obj:`datetime.datetime```
-
+flask code object          :py:obj:`flask.Flask`              ``:py:obj:`flask.Flask```
-
+========================== ================================== ====================================
-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
 
 
 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
+Refer to `Sphinx Roles`_ for roles added by Sphinx.
-#. ``=`` for chapters
-#. ``-`` for sections
-#. ``~`` for subsections
 
-.. _reST template:
 
-.. admonition:: reST template
+Figures & Images
-   :class: rst-example
+================
+
+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
 
-       .. _document title:
+   .. _svg image example:
 
-       ==============
+   .. kernel-figure:: svg_image.svg
-       Document title
+      :alt: simple SVG image
-       ==============
 
-       Lorem ipsum dolor sit amet, consectetur adipisici elit ..
+      SVG image example
-       Further read :ref:`chapter title`.
 
-       .. _chapter title:
+.. _svg image example:
 
-       Chapters
+.. kernel-figure:: svg_image.svg
-       ========
+   :alt: simple SVG image
 
-       Ut enim ad minim veniam, quis nostrud exercitation ullamco
+   SVG image example
-       laboris nisi ut aliquid ex ea commodi consequat ...
 
-       Section
+DOT files (aka Graphviz)
-       -------
+------------------------
 
-       lorem ..
+The kernel figure (and image) directive support **DOT** formated files, see
 
-       Subsection
+* 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
+
+   .. kernel-figure:: hello.dot
+      :alt: hello world
+
+      DOT's hello world example
+
+``kernel-render`` DOT
+---------------------
+
+Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
+``kernel-render`` directives.
+
+.. code:: reST
+
+   .. kernel-render:: DOT markup
+      :alt: foobar digraph
+      :caption: Embedded **DOT** (Graphviz) code
+
+      digraph foo {
+        "bar" -> "baz";
+      }
+
+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`).
+
+.. admonition:: DOT markup
+   :class: rst-example
+
+   .. _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

docs/dev/svg_image.svg

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- originate: https://commons.wikimedia.org/wiki/File:Variable_Resistor.svg -->
+<svg xmlns="http://www.w3.org/2000/svg"
+	version="1.1" baseProfile="full"
+	width="70px" height="40px" viewBox="0 0 700 400">
+	<line x1="0" y1="200" x2="700" y2="200" stroke="black" stroke-width="20px"/>
+	<rect x="100" y="100" width="500" height="200" fill="white" stroke="black" stroke-width="20px"/>
+	<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>

requirements-dev.txt

@@ -11,3 +11,4 @@ transifex-client==0.12.2
 unittest2==1.1.0
 zope.testrunner==4.5.1
 selenium==3.141.0
+linuxdoc @ git+http://github.com/return42/linuxdoc.git