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>
This commit is contained in:
Markus Heiser 2019-12-28 01:01:11 +01:00
parent 92afe68d65
commit d6f2802e4b
2 changed files with 222 additions and 57 deletions

View file

@ -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',

View file

@ -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 its 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_.
others are basic-tabs_ and code-tabs_. Below a *group-tab* example from
:ref:`docs build` is shown:
.. literalinclude:: ../admin/buildhosts.rst
:language: reST
:start-after: .. _system requirements:
:end-before: .. _system requirements END:
.. _math:
Math equations
==============
.. _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
.. sidebar:: About LaTeX
- `amsmath user guide`_
- Mathematics_
- :ref:`docs build`
The input language for mathematics is LaTeX markup using the :ctan:`amsmath`
package.
To embed LaTeX markup in reST documents, use role :rst:role:`:math: <math>` for
inline and directive :rst:dir:`.. math:: <math>` for block markup.
.. code:: reST
.. tabs::
In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
is shown.
.. group-tab:: Linux
.. math::
:label: schroedinger general
Linux Line 1
\mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
\hat{H} |\,\psi (t) \rangle.
.. group-tab:: Mac OSX
Mac OSX Line 1
.. group-tab:: Windows
Windows Line 1
.. tabs::
.. group-tab:: Linux
Linux Line 1
.. group-tab:: Mac OSX
Mac OSX Line 1
.. group-tab:: Windows
Windows Line 1
.. admonition:: Tabbed view (grouped)
.. admonition:: LaTeX math equation
:class: rst-example
.. tabs::
In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
is shown.
.. group-tab:: Linux
.. math::
:label: schroedinger general
Linux Line 1
\mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
\hat{H} |\,\psi (t) \rangle.
.. group-tab:: Mac OSX
Mac OSX Line 1
The next example shows the difference of ``\tfrac`` (*textstyle*) and ``\dfrac``
(*displaystyle*) used in a inline markup or another fraction.
.. group-tab:: Windows
.. code:: reST
Windows 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}`
.. tabs::
.. admonition:: Line spacing
:class: rst-example
.. group-tab:: Linux
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.
Linux Line 1
.. group-tab:: Mac OSX
Mac OSX Line 1
.. group-tab:: Windows
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:`\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