OwlBurst/Ponysearch
1
0
Fork 0
forked from Ponysearch/Ponysearch
Code Pull requests Activity

docs: reST-primer first proofreading (WIP)

Browse source 
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
1 changed files with 100 additions and 52 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

152
docs/dev/reST.rst
View file

@ -28,6 +28,9 @@ The sources of Searx's documentation are located at :origin:`docs`. Run
- intersphinx_ - intersphinx_
- `Sphinx's autodoc`_ - `Sphinx's autodoc`_
- `Sphinx's Python domain`_, `Sphinx's C domain`_ - `Sphinx's Python domain`_, `Sphinx's C domain`_
- SVG_, ImageMagick_
- DOT_, `Graphviz's dot`_, Graphviz_
.. contents:: Contents .. contents:: Contents
:depth: 3 :depth: 3
@ -76,9 +79,9 @@ Admin's POV: :origin:`docs/admin`
Developer's POV: :origin:`docs/dev` Developer's POV: :origin:`docs/dev`
Depending on the readability_ of code, a typical developer is able to read and 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), 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 If the chronological order matters, describe it. Name the *out-of-limits
condition* and all the side effects a external developer will not know. conditions* and all the side effects a external developer will not know.
.. _reST inline markup: .. _reST inline markup:
@ -254,7 +257,7 @@ Intersphinx is configured in :origin:`docs/conf.py`:
intersphinx_mapping = { intersphinx_mapping = {
"python": ("https://docs.python.org/3/", None), "python": ("https://docs.python.org/3/", None),
"flask": ("https://flask.palletsprojects.com/", 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), "linuxdoc" : ("https://return42.github.io/linuxdoc/", None),
"sphinx" : ("https://www.sphinx-doc.org/en/master/", 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 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; Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scalable here means;
scalable in sense of the build process. Normally in absence of a converter 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 tool, the build process will break. From the authors POV it’s 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 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 ``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 .. code:: reST
.. _svg image example: .. _svg image example:
.. kernel-figure:: svg_image.svg .. 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: .. _svg image example:
.. kernel-figure:: svg_image.svg .. 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) 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's dot`_
* Graphviz: http://www.graphviz.org/content/dot-language - DOT_
- Graphviz_
A simple example (:ref:`hello_dot_file`): A simple example is shown in :ref:`dot file example`:
.. code:: reST .. code:: reST
.. _dot file example:
.. kernel-figure:: hello.dot .. kernel-figure:: hello.dot
:alt: hello world :alt: hello world
@ -345,6 +362,8 @@ A simple example (:ref:`hello_dot_file`):
.. admonition:: hello.dot .. admonition:: hello.dot
:class: rst-example :class: rst-example
.. _dot file example:
.. kernel-figure:: hello.dot .. kernel-figure:: hello.dot
:alt: hello world :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 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 .. _dot render example:
: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 .. kernel-render:: DOT
:alt: foobar digraph :alt: digraph
:caption: Embedded **DOT** (Graphviz) code :caption: Embedded DOT (Graphviz) code
digraph foo { digraph foo {
"bar" -> "baz"; "bar" -> "baz";
} }
The *render* directive has all the options known from the *figure* directive, Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
plus option ``caption``. If ``caption`` has a value, a *figure* node is render example`.
inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if
you want to refer it (:ref:`hello_svg_render`).
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 ``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 :caption: Embedded **SVG** markup
:alt: so-nw-arrow :alt: so-nw-arrow
.. ..
.. code:: xml .. code:: xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" <svg xmlns="http://www.w3.org/2000/svg" version="1.1"
version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400"> baseProfile="full" width="70px" height="40px"
<line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/> viewBox="0 0 700 400"
<polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/> >
<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> </svg>
.. admonition:: SVG markup .. admonition:: kernel-render SVG
:class: rst-example :class: rst-example
.. _hello_svg_render: .. _svg render example:
.. kernel-render:: SVG .. kernel-render:: SVG
:caption: Embedded **SVG** markup :caption: Embedded **SVG** markup
:alt: so-nw-arrow :alt: so-nw-arrow
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" <svg xmlns="http://www.w3.org/2000/svg" version="1.1"
version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400"> baseProfile="full" width="70px" height="40px"
<line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/> viewBox="0 0 700 400"
<polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/> >
<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> </svg>
.. _reST lists: .. _reST lists:
List markups List markups
@ -551,7 +593,7 @@ are mappings from field names to field bodies. They marked up like this:
:fieldname: Field content :fieldname: Field content
:foo: first paragraph in field foo :foo: first paragraph in field foo
second paragraph in field foo second paragraph in field foo
:bar: Field content :bar: Field content
@ -561,7 +603,7 @@ are mappings from field names to field bodies. They marked up like this:
:fieldname: Field content :fieldname: Field content
:foo: first paragraph in field foo :foo: first paragraph in field foo
second paragraph in field foo second paragraph in field foo
:bar: Field content :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: http://docutils.sourceforge.net/docs/index.html
.. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html .. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html
.. _linuxdoc: https://return42.github.io/linuxdoc .. _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