docs: reST-primer first proofreading (WIP)

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
This commit is contained in:
Markus Heiser 2019-12-20 12:10:43 +01:00
parent b82f61f704
commit ae7cb5937e

View File

@ -28,6 +28,9 @@ The sources of Searx's documentation are located at :origin:`docs`. Run
- intersphinx_
- `Sphinx's autodoc`_
- `Sphinx's Python domain`_, `Sphinx's C domain`_
- SVG_, ImageMagick_
- DOT_, `Graphviz's dot`_, Graphviz_
.. contents:: Contents
:depth: 3
@ -76,9 +79,9 @@ Admin's POV: :origin:`docs/admin`
Developer's POV: :origin:`docs/dev`
Depending on the readability_ of code, a typical developer is able to read and
understand source code. Describe what a item aims to do (e.g. a function),
describe chronological order matters, describe it. Name the *out-of-limits
condition* and all the side effects a external developer will not know.
understand source code. Describe what a item aims to do (e.g. a function).
If the chronological order matters, describe it. Name the *out-of-limits
conditions* and all the side effects a external developer will not know.
.. _reST inline markup:
@ -254,7 +257,7 @@ Intersphinx is configured in :origin:`docs/conf.py`:
intersphinx_mapping = {
"python": ("https://docs.python.org/3/", None),
"flask": ("https://flask.palletsprojects.com/", None),
"jinja": ("https://jinja.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),
}
@ -298,6 +301,12 @@ Refer to `Sphinx Roles`_ for roles added by Sphinx.
Figures & Images
================
.. sidebar:: Image processing
With the directives from :ref:`linuxdoc <linuxdoc:kfigure>` the build process
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
tool, the build process will break. From the authors POV its annoying to care
@ -307,36 +316,44 @@ 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`):
format use SVG (:ref:`svg image example`):
.. code:: reST
.. _svg image example:
.. kernel-figure:: svg_image.svg
:alt: simple SVG image
:alt: SVG image example
SVG image example
simple SVG image
To refer the figure, a caption block is needed: :ref:`svg image example`.
.. _svg image example:
.. kernel-figure:: svg_image.svg
:alt: simple SVG image
:alt: SVG image example
SVG image example
simple SVG image
To refer the figure, a caption block is needed: :ref:`svg image example`.
DOT files (aka Graphviz)
------------------------
The kernel figure (and image) directive support **DOT** formated files, see
With :ref:`linuxdoc:kernel-figure` reST support for **DOT** formatted files is
given.
* DOT: http://graphviz.org/pdf/dotguide.pdf
* Graphviz: http://www.graphviz.org/content/dot-language
- `Graphviz's dot`_
- DOT_
- Graphviz_
A simple example (:ref:`hello_dot_file`):
A simple example is shown in :ref:`dot file example`:
.. code:: reST
.. _dot file example:
.. kernel-figure:: hello.dot
:alt: hello world
@ -345,6 +362,8 @@ A simple example (:ref:`hello_dot_file`):
.. admonition:: hello.dot
:class: rst-example
.. _dot file example:
.. kernel-figure:: hello.dot
:alt: hello world
@ -354,77 +373,100 @@ A simple example (:ref:`hello_dot_file`):
---------------------
Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
``kernel-render`` directives.
:ref:`linuxdoc:kernel-render` directive. A simple example of embedded DOT_ is
shown in figure :ref:`dot render example`:
.. code:: reST
.. code-block:: rst
.. 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:
.. _dot render example:
.. kernel-render:: DOT
:alt: foobar digraph
:caption: Embedded **DOT** (Graphviz) code
:alt: 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`).
Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
render example`.
Please note :ref:`build tools <linuxdoc:kfigure_build_tools>`. If Graphviz_ is
installed, you will see an vector image. If not, the raw markup is inserted as
*literal-block*.
.. admonition:: kernel-render DOT
:class: rst-example
.. _dot render example:
.. kernel-render:: DOT
:alt: digraph
:caption: Embedded DOT (Graphviz) code
digraph foo {
"bar" -> "baz";
}
Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
render example`.
``kernel-render`` SVG
---------------------
.. code:: reST
A simple example of embedded SVG_ is shown in figure :ref:`svg render example`:
.. kernel-render:: SVG markup
.. code-block:: rst
.. _svg render example:
.. kernel-render:: SVG
:caption: Embedded **SVG** markup
:alt: so-nw-arrow
..
.. code:: xml
.. 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 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
.. admonition:: kernel-render SVG
:class: rst-example
.. _hello_svg_render:
.. _svg render example:
.. 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 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>
.. _reST lists:
List markups
@ -551,7 +593,7 @@ are mappings from field names to field bodies. They marked up like this:
:fieldname: Field content
:foo: first paragraph in field foo
second paragraph in field foo
second paragraph in field foo
:bar: Field content
@ -561,7 +603,7 @@ are mappings from field names to field bodies. They marked up like this:
:fieldname: Field content
:foo: first paragraph in field foo
second paragraph in field foo
second paragraph in field foo
:bar: Field content
@ -684,3 +726,9 @@ Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
.. _docutils: http://docutils.sourceforge.net/docs/index.html
.. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html
.. _linuxdoc: https://return42.github.io/linuxdoc
.. _SVG: https://www.w3.org/TR/SVG11/expanded-toc.html
.. _DOT: https://graphviz.gitlab.io/_pages/doc/info/lang.html
.. _`Graphviz's dot`: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf
.. _Graphviz: https://graphviz.gitlab.io
.. _ImageMagick: https://www.imagemagick.org