2019-12-19 16:05:50 +00:00
|
|
|
|
.. _reST primer:
|
|
|
|
|
|
|
|
|
|
===========
|
|
|
|
|
reST primer
|
|
|
|
|
===========
|
|
|
|
|
|
|
|
|
|
.. sidebar:: KISS_ and readability_
|
|
|
|
|
|
|
|
|
|
Instead of defining more and more roles, we at searx encourage our
|
|
|
|
|
contributors to follow principles like KISS_ and readability_.
|
|
|
|
|
|
|
|
|
|
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 <.>`.
|
|
|
|
|
|
|
|
|
|
The sources of Searx's documentation are located at :origin:`docs`. Run
|
|
|
|
|
:ref:`make docs-live <make docs-live>` to build HTML while editing.
|
|
|
|
|
|
2019-12-19 22:36:53 +00:00
|
|
|
|
.. sidebar:: Further reading
|
|
|
|
|
|
|
|
|
|
- Sphinx-Primer_
|
|
|
|
|
- `Sphinx markup constructs`_
|
|
|
|
|
- reST_, docutils_, `docutils FAQ`_
|
|
|
|
|
- Sphinx_, `sphinx-doc FAQ`_
|
|
|
|
|
- `sphinx config`_, doctree_
|
|
|
|
|
- `sphinx cross references`_
|
|
|
|
|
- linuxdoc_
|
|
|
|
|
- intersphinx_
|
2019-12-21 16:13:38 +00:00
|
|
|
|
- sphinx-jinja_
|
2019-12-19 22:36:53 +00:00
|
|
|
|
- `Sphinx's autodoc`_
|
|
|
|
|
- `Sphinx's Python domain`_, `Sphinx's C domain`_
|
2019-12-20 11:10:43 +00:00
|
|
|
|
- SVG_, ImageMagick_
|
|
|
|
|
- DOT_, `Graphviz's dot`_, Graphviz_
|
|
|
|
|
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
2019-12-19 16:05:50 +00:00
|
|
|
|
.. 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]`_.
|
|
|
|
|
|
|
|
|
|
.. _[kernel doc]: https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html
|
|
|
|
|
|
|
|
|
|
.. sidebar:: Content matters
|
|
|
|
|
|
|
|
|
|
The readability_ of the reST sources has its value, therefore we recommend to
|
|
|
|
|
make sparse usage of reST markup / .. content matters!
|
|
|
|
|
|
|
|
|
|
**reST** is a plaintext markup language, its markup is *mostly* intuitive and
|
|
|
|
|
you will not need to learn much to produce well formed articles with. I use the
|
|
|
|
|
word *mostly*: like everything in live, reST has its advantages and
|
|
|
|
|
disadvantages, some markups feel a bit grumpy (especially if you are used to
|
|
|
|
|
other plaintext markups).
|
|
|
|
|
|
|
|
|
|
Soft skills
|
|
|
|
|
===========
|
|
|
|
|
|
|
|
|
|
Before going any deeper into the markup let's face on some **soft skills** a
|
|
|
|
|
trained author brings with, to reach a well feedback from readers:
|
|
|
|
|
|
|
|
|
|
- Documentation is dedicated to an audience and answers questions from the
|
|
|
|
|
audience point of view.
|
|
|
|
|
- Don't detail things which are general knowledge from the audience point of
|
|
|
|
|
view.
|
|
|
|
|
- Limit the subject, use cross links for any further reading.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
User's POV: :origin:`docs/user`
|
|
|
|
|
A typical user knows about search engines and might have heard about
|
|
|
|
|
meta crawlers and privacy.
|
|
|
|
|
|
|
|
|
|
Admin's POV: :origin:`docs/admin`
|
|
|
|
|
A typical Admin knows about setting up services on a linux system, but he does
|
|
|
|
|
not know all the pros and cons of a searx setup.
|
|
|
|
|
|
|
|
|
|
Developer's POV: :origin:`docs/dev`
|
|
|
|
|
Depending on the readability_ of code, a typical developer is able to read and
|
2019-12-20 11:10:43 +00:00
|
|
|
|
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.
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
|
|
|
|
.. _reST inline markup:
|
|
|
|
|
|
|
|
|
|
Basic inline markup
|
|
|
|
|
===================
|
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
.. sidebar:: Inline markup
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
- :ref:`reST roles`
|
|
|
|
|
- :ref:`reST smart ref`
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
Basic inline markup is done with asterisks and backquotes. If asterisks or
|
|
|
|
|
backquotes appear in running text and could be confused with inline markup
|
|
|
|
|
delimiters, they have to be escaped with a backslash (``\*pointer``).
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-20 19:39:14 +00:00
|
|
|
|
.. table:: basic inline markup
|
|
|
|
|
:widths: 4 3 7
|
|
|
|
|
|
|
|
|
|
================================================ ==================== ========================
|
|
|
|
|
description rendered markup
|
|
|
|
|
================================================ ==================== ========================
|
|
|
|
|
one asterisk for emphasis *italics* ``*italics*``
|
|
|
|
|
two asterisks for strong emphasis **boldface** ``**boldface**``
|
|
|
|
|
backquotes for code samples and literals ``foo()`` ````foo()````
|
|
|
|
|
quote asterisks or backquotes \*foo is a pointer ``\*foo is a pointer``
|
|
|
|
|
================================================ ==================== ========================
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-19 22:36:53 +00:00
|
|
|
|
.. _reST basic structure:
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-19 22:36:53 +00:00
|
|
|
|
Basic article structure
|
|
|
|
|
=======================
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-19 22:36:53 +00:00
|
|
|
|
The basic structure of an article makes use of heading adornments to markup
|
|
|
|
|
chapter, sections and subsections.
|
|
|
|
|
|
|
|
|
|
.. _reST template:
|
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
reST template
|
|
|
|
|
-------------
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
reST template for an simple article:
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
|
|
|
|
.. _doc refname:
|
|
|
|
|
|
|
|
|
|
==============
|
|
|
|
|
Document title
|
|
|
|
|
==============
|
|
|
|
|
|
|
|
|
|
Lorem ipsum dolor sit amet, consectetur adipisici elit .. Further read
|
|
|
|
|
:ref:`chapter refname`.
|
|
|
|
|
|
|
|
|
|
.. _chapter refname:
|
|
|
|
|
|
|
|
|
|
Chapter
|
|
|
|
|
=======
|
|
|
|
|
|
|
|
|
|
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
|
|
|
|
|
aliquid ex ea commodi consequat ...
|
|
|
|
|
|
|
|
|
|
.. _section refname:
|
|
|
|
|
|
|
|
|
|
Section
|
|
|
|
|
-------
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
lorem ..
|
|
|
|
|
|
|
|
|
|
.. _subsection refname:
|
|
|
|
|
|
|
|
|
|
Subsection
|
|
|
|
|
~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
lorem ..
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Headings
|
|
|
|
|
--------
|
|
|
|
|
|
|
|
|
|
#. title - with overline for document title:
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
|
|
|
|
==============
|
|
|
|
|
Document title
|
|
|
|
|
==============
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#. chapter - with anchor named ``anchor name``:
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
.. _anchor name:
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
Chapter
|
|
|
|
|
=======
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
#. section
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
.. code:: reST
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
Section
|
|
|
|
|
-------
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
#. subsection
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
.. code:: reST
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
Subsection
|
|
|
|
|
~~~~~~~~~~
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Anchors & Links
|
|
|
|
|
===============
|
|
|
|
|
|
|
|
|
|
.. _reST anchor:
|
|
|
|
|
|
|
|
|
|
Anchors
|
|
|
|
|
-------
|
|
|
|
|
|
|
|
|
|
.. _ref role:
|
|
|
|
|
https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
|
|
|
|
|
|
|
|
|
|
To refer a point in the documentation a anchor is needed. The :ref:`reST
|
|
|
|
|
template <reST template>` shows an example where a chapter titled *"Chapters"*
|
|
|
|
|
gets an anchor named ``chapter title``. Another example from *this* document,
|
|
|
|
|
where the anchor named ``reST anchor``:
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
|
|
|
|
.. _reST anchor:
|
|
|
|
|
|
|
|
|
|
Anchors
|
|
|
|
|
-------
|
|
|
|
|
|
|
|
|
|
To refer a point in the documentation a anchor is needed ...
|
|
|
|
|
|
|
|
|
|
To refer anchors use the `ref role`_ markup:
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
Visit chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
|
|
|
|
|
bar <reST anchor>`.
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
|
|
|
|
.. admonition:: ``:ref:`` role
|
|
|
|
|
:class: rst-example
|
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
Visist chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
|
|
|
|
|
bar <reST anchor>`.
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
|
|
|
|
.. _reST ordinary ref:
|
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
Link ordinary URL
|
2019-12-19 16:05:50 +00:00
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
|
|
If you need to reference external URLs use *named* hyperlinks to maintain
|
|
|
|
|
readability of reST sources. Here is a example taken from *this* article:
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
|
|
|
|
.. _Sphinx Field Lists:
|
|
|
|
|
https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
|
|
|
|
|
|
|
|
|
|
With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more
|
|
|
|
|
readable.
|
|
|
|
|
|
|
|
|
|
And this shows the alternative (less readable) hyperlink markup `Sphinx Field
|
|
|
|
|
Lists
|
|
|
|
|
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`__.
|
|
|
|
|
|
|
|
|
|
.. admonition:: Named hyperlink
|
|
|
|
|
:class: rst-example
|
|
|
|
|
|
|
|
|
|
With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more
|
|
|
|
|
readable.
|
|
|
|
|
|
|
|
|
|
And this shows the alternative (less readable) hyperlink markup `Sphinx Field
|
|
|
|
|
Lists
|
|
|
|
|
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`__.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. _reST smart ref:
|
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
Smart refs
|
|
|
|
|
----------
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
|
|
|
|
With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
|
2019-12-19 22:36:53 +00:00
|
|
|
|
content becomes smart.
|
|
|
|
|
|
2019-12-20 19:39:14 +00:00
|
|
|
|
.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_
|
|
|
|
|
:widths: 4 3 7
|
|
|
|
|
|
|
|
|
|
========================== ================================== ====================================
|
|
|
|
|
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```
|
|
|
|
|
========================== ================================== ====================================
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Intersphinx is configured in :origin:`docs/conf.py`:
|
|
|
|
|
|
|
|
|
|
.. code:: python
|
|
|
|
|
|
|
|
|
|
intersphinx_mapping = {
|
|
|
|
|
"python": ("https://docs.python.org/3/", None),
|
|
|
|
|
"flask": ("https://flask.palletsprojects.com/", None),
|
2019-12-20 11:10:43 +00:00
|
|
|
|
"jinja": ("https://jinja.palletsprojects.com/", None),
|
2019-12-19 22:36:53 +00:00
|
|
|
|
"linuxdoc" : ("https://return42.github.io/linuxdoc/", None),
|
|
|
|
|
"sphinx" : ("https://www.sphinx-doc.org/en/master/", None),
|
2019-12-19 16:05:50 +00:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
To list all anchors of the inventory (e.g. ``python``) use:
|
|
|
|
|
|
|
|
|
|
.. code:: sh
|
|
|
|
|
|
|
|
|
|
$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
|
|
|
|
|
|
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
.. _reST roles:
|
|
|
|
|
|
2019-12-19 22:36:53 +00:00
|
|
|
|
Roles
|
|
|
|
|
=====
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-20 19:39:14 +00:00
|
|
|
|
.. sidebar:: Further reading
|
|
|
|
|
|
|
|
|
|
- `Sphinx Roles`_
|
|
|
|
|
- :doc:`sphinx:usage/restructuredtext/domains`
|
|
|
|
|
|
|
|
|
|
|
2019-12-19 22:36:53 +00:00
|
|
|
|
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
|
2019-12-20 19:39:14 +00:00
|
|
|
|
in a specific way.
|
|
|
|
|
|
|
|
|
|
The general markup is one of:
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-20 19:39:14 +00:00
|
|
|
|
:rolename:`ref-name`
|
|
|
|
|
:rolename:`ref text <ref-name>`
|
|
|
|
|
|
|
|
|
|
.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_
|
|
|
|
|
:widths: 4 3 7
|
|
|
|
|
|
|
|
|
|
========================== ================================== ====================================
|
|
|
|
|
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```
|
|
|
|
|
========================== ================================== ====================================
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-19 22:36:53 +00:00
|
|
|
|
Figures & Images
|
|
|
|
|
================
|
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
.. 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_.
|
|
|
|
|
|
2019-12-19 22:36:53 +00:00
|
|
|
|
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
|
2019-12-20 11:10:43 +00:00
|
|
|
|
format use SVG (:ref:`svg image example`):
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
|
|
|
|
.. _svg image example:
|
|
|
|
|
|
|
|
|
|
.. kernel-figure:: svg_image.svg
|
2019-12-20 11:10:43 +00:00
|
|
|
|
:alt: SVG image example
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
simple SVG image
|
|
|
|
|
|
|
|
|
|
To refer the figure, a caption block is needed: :ref:`svg image example`.
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
|
|
|
|
.. _svg image example:
|
|
|
|
|
|
|
|
|
|
.. kernel-figure:: svg_image.svg
|
2019-12-20 11:10:43 +00:00
|
|
|
|
:alt: SVG image example
|
|
|
|
|
|
|
|
|
|
simple SVG image
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
To refer the figure, a caption block is needed: :ref:`svg image example`.
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
|
|
|
|
DOT files (aka Graphviz)
|
|
|
|
|
------------------------
|
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
With :ref:`linuxdoc:kernel-figure` reST support for **DOT** formatted files is
|
|
|
|
|
given.
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
- `Graphviz's dot`_
|
|
|
|
|
- DOT_
|
|
|
|
|
- Graphviz_
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
A simple example is shown in :ref:`dot file example`:
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
.. _dot file example:
|
|
|
|
|
|
2019-12-19 22:36:53 +00:00
|
|
|
|
.. kernel-figure:: hello.dot
|
|
|
|
|
:alt: hello world
|
|
|
|
|
|
|
|
|
|
DOT's hello world example
|
|
|
|
|
|
|
|
|
|
.. admonition:: hello.dot
|
2019-12-19 16:05:50 +00:00
|
|
|
|
:class: rst-example
|
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
.. _dot file example:
|
|
|
|
|
|
2019-12-19 22:36:53 +00:00
|
|
|
|
.. kernel-figure:: hello.dot
|
|
|
|
|
:alt: hello world
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-19 22:36:53 +00:00
|
|
|
|
DOT's hello world example
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-19 22:36:53 +00:00
|
|
|
|
``kernel-render`` DOT
|
|
|
|
|
---------------------
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-19 22:36:53 +00:00
|
|
|
|
Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
|
2019-12-20 11:10:43 +00:00
|
|
|
|
:ref:`linuxdoc:kernel-render` directive. A simple example of embedded DOT_ is
|
|
|
|
|
shown in figure :ref:`dot render example`:
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-20 19:39:14 +00:00
|
|
|
|
.. code:: reST
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
.. _dot render example:
|
|
|
|
|
|
|
|
|
|
.. kernel-render:: DOT
|
|
|
|
|
:alt: digraph
|
|
|
|
|
:caption: Embedded DOT (Graphviz) code
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-19 22:36:53 +00:00
|
|
|
|
digraph foo {
|
|
|
|
|
"bar" -> "baz";
|
|
|
|
|
}
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
|
|
|
|
|
render example`.
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
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
|
2019-12-19 22:36:53 +00:00
|
|
|
|
:class: rst-example
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
.. _dot render example:
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
|
|
|
|
.. kernel-render:: DOT
|
2019-12-20 11:10:43 +00:00
|
|
|
|
:alt: digraph
|
|
|
|
|
:caption: Embedded DOT (Graphviz) code
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
|
|
|
|
digraph foo {
|
|
|
|
|
"bar" -> "baz";
|
|
|
|
|
}
|
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
|
|
|
|
|
render example`.
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
|
|
|
|
``kernel-render`` SVG
|
|
|
|
|
---------------------
|
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
A simple example of embedded SVG_ is shown in figure :ref:`svg render example`:
|
|
|
|
|
|
2019-12-20 19:39:14 +00:00
|
|
|
|
.. code:: reST
|
2019-12-20 11:10:43 +00:00
|
|
|
|
|
|
|
|
|
.. _svg render example:
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
.. kernel-render:: SVG
|
2019-12-19 22:36:53 +00:00
|
|
|
|
:caption: Embedded **SVG** markup
|
|
|
|
|
:alt: so-nw-arrow
|
|
|
|
|
..
|
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
.. code:: xml
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
|
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
2019-12-20 11:10:43 +00:00
|
|
|
|
<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)"
|
|
|
|
|
/>
|
2019-12-19 22:36:53 +00:00
|
|
|
|
</svg>
|
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
.. admonition:: kernel-render SVG
|
2019-12-19 22:36:53 +00:00
|
|
|
|
:class: rst-example
|
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
.. _svg render example:
|
2019-12-19 22:36:53 +00:00
|
|
|
|
|
|
|
|
|
.. kernel-render:: SVG
|
|
|
|
|
:caption: Embedded **SVG** markup
|
|
|
|
|
:alt: so-nw-arrow
|
|
|
|
|
|
|
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
2019-12-20 11:10:43 +00:00
|
|
|
|
<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)"
|
|
|
|
|
/>
|
2019-12-19 22:36:53 +00:00
|
|
|
|
</svg>
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
|
|
|
|
|
|
2019-12-19 16:05:50 +00:00
|
|
|
|
.. _reST lists:
|
|
|
|
|
|
|
|
|
|
List markups
|
|
|
|
|
============
|
|
|
|
|
|
|
|
|
|
Bullet list
|
|
|
|
|
-----------
|
|
|
|
|
|
|
|
|
|
List markup (:duref:`ref <bullet-lists>`) is simple:
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
|
|
|
|
- This is a bulleted list.
|
|
|
|
|
|
|
|
|
|
1. Nested lists are possible, but be aware that they must be separated from
|
|
|
|
|
the parent list items by blank line
|
|
|
|
|
2. Second item of nested list
|
|
|
|
|
|
|
|
|
|
- It has two items, the second
|
|
|
|
|
item uses two lines.
|
|
|
|
|
|
|
|
|
|
#. This is a numbered list.
|
|
|
|
|
#. It has two items too.
|
|
|
|
|
|
|
|
|
|
.. admonition:: bullet list
|
|
|
|
|
:class: rst-example
|
|
|
|
|
|
|
|
|
|
- This is a bulleted list.
|
|
|
|
|
|
|
|
|
|
1. Nested lists are possible, but be aware that they must be separated from
|
|
|
|
|
the parent list items by blank line
|
|
|
|
|
2. Second item of nested list
|
|
|
|
|
|
|
|
|
|
- It has two items, the second
|
|
|
|
|
item uses two lines.
|
|
|
|
|
|
|
|
|
|
#. This is a numbered list.
|
|
|
|
|
#. It has two items too.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Definition list
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
|
|
.. sidebar:: definition term
|
|
|
|
|
|
|
|
|
|
Note that the term cannot have more than one line of text.
|
|
|
|
|
|
|
|
|
|
Definition lists (:duref:`ref <definition-lists>`) are created as follows:
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
|
|
|
|
term (up to a line of text)
|
|
|
|
|
Definition of the term, which must be indented
|
|
|
|
|
|
|
|
|
|
and can even consist of multiple paragraphs
|
|
|
|
|
|
|
|
|
|
next term
|
|
|
|
|
Description.
|
|
|
|
|
|
|
|
|
|
.. admonition:: definition list
|
|
|
|
|
:class: rst-example
|
|
|
|
|
|
|
|
|
|
term (up to a line of text)
|
|
|
|
|
Definition of the term, which must be indented
|
|
|
|
|
|
|
|
|
|
and can even consist of multiple paragraphs
|
|
|
|
|
|
|
|
|
|
next term
|
|
|
|
|
Description.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Quoted paragraphs
|
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
|
|
Quoted paragraphs (:duref:`ref <block-quotes>`) are created by just indenting
|
|
|
|
|
them more than the surrounding paragraphs. Line blocks (:duref:`ref
|
|
|
|
|
<line-blocks>`) are a way of preserving line breaks:
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
|
|
|
|
normal paragraph ...
|
|
|
|
|
lorem ipsum.
|
|
|
|
|
|
|
|
|
|
Quoted paragraph ...
|
|
|
|
|
lorem ipsum.
|
|
|
|
|
|
|
|
|
|
| These lines are
|
|
|
|
|
| broken exactly like in
|
|
|
|
|
| the source file.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. admonition:: Quoted paragraph and line block
|
|
|
|
|
:class: rst-example
|
|
|
|
|
|
|
|
|
|
normal paragraph ...
|
|
|
|
|
lorem ipsum.
|
|
|
|
|
|
|
|
|
|
Quoted paragraph ...
|
|
|
|
|
lorem ipsum.
|
|
|
|
|
|
|
|
|
|
| These lines are
|
|
|
|
|
| broken exactly like in
|
|
|
|
|
| the source file.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. _reST field list:
|
|
|
|
|
|
|
|
|
|
Field Lists
|
|
|
|
|
-----------
|
|
|
|
|
|
|
|
|
|
.. _Sphinx Field Lists:
|
|
|
|
|
https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
|
|
|
|
|
|
|
|
|
|
.. sidebar:: bibliographic fields
|
|
|
|
|
|
|
|
|
|
First lines fields are bibliographic fields, see `Sphinx Field Lists`_.
|
|
|
|
|
|
|
|
|
|
Field lists are used as part of an extension syntax, such as options for
|
|
|
|
|
directives, or database-like records meant for further processing. Field lists
|
|
|
|
|
are mappings from field names to field bodies. They marked up like this:
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
|
|
|
|
:fieldname: Field content
|
|
|
|
|
:foo: first paragraph in field foo
|
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
second paragraph in field foo
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
|
|
|
|
:bar: Field content
|
|
|
|
|
|
|
|
|
|
.. admonition:: Field List
|
|
|
|
|
:class: rst-example
|
|
|
|
|
|
|
|
|
|
:fieldname: Field content
|
|
|
|
|
:foo: first paragraph in field foo
|
|
|
|
|
|
2019-12-20 11:10:43 +00:00
|
|
|
|
second paragraph in field foo
|
2019-12-19 16:05:50 +00:00
|
|
|
|
|
|
|
|
|
:bar: Field content
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
They are commonly used in Python documentation:
|
|
|
|
|
|
|
|
|
|
.. code:: python
|
|
|
|
|
|
|
|
|
|
def my_function(my_arg, my_other_arg):
|
|
|
|
|
"""A function just for me.
|
|
|
|
|
|
|
|
|
|
:param my_arg: The first of my arguments.
|
|
|
|
|
:param my_other_arg: The second of my arguments.
|
|
|
|
|
|
|
|
|
|
:returns: A message (just for me, of course).
|
|
|
|
|
"""
|
|
|
|
|
|
|
|
|
|
Further list blocks
|
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
|
|
- field lists (:duref:`ref <field-lists>`, with caveats noted in
|
|
|
|
|
:ref:`reST field list`)
|
|
|
|
|
- option lists (:duref:`ref <option-lists>`)
|
|
|
|
|
- quoted literal blocks (:duref:`ref <quoted-literal-blocks>`)
|
|
|
|
|
- doctest blocks (:duref:`ref <doctest-blocks>`)
|
|
|
|
|
|
|
|
|
|
|
2019-12-20 10:01:41 +00:00
|
|
|
|
Admonitions
|
|
|
|
|
===========
|
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
Sidebar
|
|
|
|
|
-------
|
|
|
|
|
|
|
|
|
|
Sidebar is an eye catcher, often used for admonitions pointing further stuff or
|
|
|
|
|
site effects. Here is the source of the sidebar :ref:`on top of this page <reST
|
|
|
|
|
primer>`.
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
|
|
|
|
.. sidebar:: KISS_ and readability_
|
|
|
|
|
|
|
|
|
|
Instead of defining more and more roles, we at searx encourage our
|
|
|
|
|
contributors to follow principles like KISS_ and readability_.
|
|
|
|
|
|
|
|
|
|
Generic admonition
|
|
|
|
|
------------------
|
|
|
|
|
|
|
|
|
|
The generic :dudir:`admonition <admonitions>` needs a title:
|
2019-12-20 10:01:41 +00:00
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
|
|
|
|
.. admonition:: generic admonition title
|
|
|
|
|
|
|
|
|
|
lorem ipsum ..
|
|
|
|
|
|
2019-12-20 16:47:24 +00:00
|
|
|
|
|
|
|
|
|
.. admonition:: generic admonition title
|
|
|
|
|
|
|
|
|
|
lorem ipsum ..
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Specific admonitions
|
|
|
|
|
--------------------
|
|
|
|
|
|
|
|
|
|
Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
|
|
|
|
|
:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, and
|
|
|
|
|
:dudir:`warning` .
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
2019-12-20 10:01:41 +00:00
|
|
|
|
.. hint::
|
|
|
|
|
|
|
|
|
|
lorem ipsum ..
|
|
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
|
|
lorem ipsum ..
|
|
|
|
|
|
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
lorem ipsum ..
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. hint::
|
|
|
|
|
|
|
|
|
|
lorem ipsum ..
|
|
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
|
|
lorem ipsum ..
|
|
|
|
|
|
|
|
|
|
.. tip::
|
|
|
|
|
|
|
|
|
|
lorem ipsum ..
|
|
|
|
|
|
|
|
|
|
.. attention::
|
|
|
|
|
|
|
|
|
|
lorem ipsum ..
|
|
|
|
|
|
|
|
|
|
.. caution::
|
|
|
|
|
|
|
|
|
|
lorem ipsum ..
|
|
|
|
|
|
|
|
|
|
.. danger::
|
|
|
|
|
|
|
|
|
|
lorem ipsum ..
|
|
|
|
|
|
|
|
|
|
.. important::
|
|
|
|
|
|
|
|
|
|
lorem ipsum ..
|
|
|
|
|
|
|
|
|
|
.. error::
|
|
|
|
|
|
|
|
|
|
lorem ipsum ..
|
|
|
|
|
|
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
lorem ipsum ..
|
|
|
|
|
|
|
|
|
|
|
2019-12-20 19:39:14 +00:00
|
|
|
|
Tables
|
|
|
|
|
======
|
|
|
|
|
|
|
|
|
|
.. sidebar:: Nested tables
|
|
|
|
|
|
|
|
|
|
Nested tables are ugly! Not all builder support nested tables, don't use
|
|
|
|
|
them!
|
|
|
|
|
|
|
|
|
|
ASCII-art tables like :ref:`reST simple table` and :ref:`reST grid table` might
|
|
|
|
|
be comfortable for readers of the text-files, but they have huge disadvantages
|
|
|
|
|
in the creation and modifying. First, they are hard to edit. Think about
|
|
|
|
|
adding a row or a column to a ASCII-art table or adding a paragraph in a cell,
|
|
|
|
|
it is a nightmare on big tables.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. sidebar:: List tables
|
|
|
|
|
|
|
|
|
|
For meaningful patch and diff use :ref:`reST flat table`.
|
|
|
|
|
|
|
|
|
|
Second the diff of modifying ASCII-art tables is not meaningful, e.g. widening a
|
|
|
|
|
cell generates a diff in which also changes are included, which are only
|
|
|
|
|
ascribable to the ASCII-art. Anyway, if you prefer ASCII-art for any reason,
|
|
|
|
|
here are some helpers:
|
|
|
|
|
|
|
|
|
|
* `Emacs Table Mode`_
|
|
|
|
|
* `Online Tables Generator`_
|
|
|
|
|
|
|
|
|
|
.. _reST simple table:
|
|
|
|
|
|
|
|
|
|
Simple tables
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
:duref:`Simple tables <simple-tables>` allow *colspan* but not *rowspan*. If
|
|
|
|
|
your table need some metadata (e.g. a title) you need to add the ``.. table::
|
|
|
|
|
directive`` :dudir:`(ref) <table>` in front and place the table in its body:
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
|
|
|
|
.. table:: foo gate truth table
|
|
|
|
|
:widths: grid
|
|
|
|
|
:align: left
|
|
|
|
|
|
|
|
|
|
====== ====== ======
|
|
|
|
|
Inputs Output
|
|
|
|
|
------------- ------
|
|
|
|
|
A B A or B
|
|
|
|
|
====== ====== ======
|
|
|
|
|
False
|
|
|
|
|
--------------------
|
|
|
|
|
True
|
|
|
|
|
--------------------
|
|
|
|
|
True False True
|
|
|
|
|
(foo)
|
|
|
|
|
------ ------ ------
|
|
|
|
|
False True
|
|
|
|
|
(foo)
|
|
|
|
|
====== =============
|
|
|
|
|
|
|
|
|
|
.. admonition:: Simple ASCII table
|
|
|
|
|
:class: rst-example
|
|
|
|
|
|
|
|
|
|
.. table:: foo gate truth table
|
|
|
|
|
:widths: grid
|
|
|
|
|
:align: left
|
|
|
|
|
|
|
|
|
|
====== ====== ======
|
|
|
|
|
Inputs Output
|
|
|
|
|
------------- ------
|
|
|
|
|
A B A or B
|
|
|
|
|
====== ====== ======
|
|
|
|
|
False
|
|
|
|
|
--------------------
|
|
|
|
|
True
|
|
|
|
|
--------------------
|
|
|
|
|
True False True
|
|
|
|
|
(foo)
|
|
|
|
|
------ ------ ------
|
|
|
|
|
False True
|
|
|
|
|
(foo)
|
|
|
|
|
====== =============
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. _reST grid table:
|
|
|
|
|
|
|
|
|
|
Grid tables
|
|
|
|
|
-----------
|
|
|
|
|
|
|
|
|
|
:duref:`Grid tables <grid-tables>` allow colspan *colspan* and *rowspan*:
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
|
|
|
|
.. table:: grid table example
|
|
|
|
|
:widths: 1 1 5
|
|
|
|
|
|
|
|
|
|
+------------+------------+-----------+
|
|
|
|
|
| Header 1 | Header 2 | Header 3 |
|
|
|
|
|
+============+============+===========+
|
|
|
|
|
| body row 1 | column 2 | column 3 |
|
|
|
|
|
+------------+------------+-----------+
|
|
|
|
|
| body row 2 | Cells may span columns.|
|
|
|
|
|
+------------+------------+-----------+
|
|
|
|
|
| body row 3 | Cells may | - Cells |
|
|
|
|
|
+------------+ span rows. | - contain |
|
|
|
|
|
| body row 4 | | - blocks. |
|
|
|
|
|
+------------+------------+-----------+
|
|
|
|
|
|
|
|
|
|
.. admonition:: ASCII grid table
|
|
|
|
|
:class: rst-example
|
|
|
|
|
|
|
|
|
|
.. table:: grid table example
|
|
|
|
|
:widths: 1 1 5
|
|
|
|
|
|
|
|
|
|
+------------+------------+-----------+
|
|
|
|
|
| Header 1 | Header 2 | Header 3 |
|
|
|
|
|
+============+============+===========+
|
|
|
|
|
| body row 1 | column 2 | column 3 |
|
|
|
|
|
+------------+------------+-----------+
|
|
|
|
|
| body row 2 | Cells may span columns.|
|
|
|
|
|
+------------+------------+-----------+
|
|
|
|
|
| body row 3 | Cells may | - Cells |
|
|
|
|
|
+------------+ span rows. | - contain |
|
|
|
|
|
| body row 4 | | - blocks. |
|
|
|
|
|
+------------+------------+-----------+
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. _reST flat table:
|
|
|
|
|
|
|
|
|
|
flat-table
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
|
|
The ``flat-table`` is a further developed variant of the :ref:`list tables
|
|
|
|
|
<linuxdoc:list-table-directives>`. It is a double-stage list similar to the
|
|
|
|
|
:dudir:`list-table` with some additional features:
|
|
|
|
|
|
|
|
|
|
column-span: ``cspan``
|
|
|
|
|
with the role ``cspan`` a cell can be extended through additional columns
|
|
|
|
|
|
|
|
|
|
row-span: ``rspan``
|
|
|
|
|
with the role ``rspan`` a cell can be extended through additional rows
|
|
|
|
|
|
|
|
|
|
auto-span:
|
|
|
|
|
spans rightmost cell of a table row over the missing cells on the right side
|
|
|
|
|
of that table-row. With Option ``:fill-cells:`` this behavior can changed
|
|
|
|
|
from *auto span* to *auto fill*, which automatically inserts (empty) cells
|
|
|
|
|
instead of spanning the last cell.
|
|
|
|
|
|
|
|
|
|
options:
|
|
|
|
|
:header-rows: [int] count of header rows
|
|
|
|
|
:stub-columns: [int] count of stub columns
|
|
|
|
|
:widths: [[int] [int] ... ] widths of columns
|
|
|
|
|
:fill-cells: instead of auto-span missing cells, insert missing cells
|
|
|
|
|
|
|
|
|
|
roles:
|
|
|
|
|
:cspan: [int] additional columns (*morecols*)
|
|
|
|
|
:rspan: [int] additional rows (*morerows*)
|
|
|
|
|
|
|
|
|
|
The example below shows how to use this markup. The first level of the staged
|
|
|
|
|
list is the *table-row*. In the *table-row* there is only one markup allowed,
|
|
|
|
|
the list of the cells in this *table-row*. Exception are *comments* ( ``..`` )
|
|
|
|
|
and *targets* (e.g. a ref to :ref:`row 2 of table's body <row body 2>`).
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
|
|
|
|
.. flat-table:: ``flat-table`` example
|
|
|
|
|
:header-rows: 2
|
|
|
|
|
:stub-columns: 1
|
|
|
|
|
:widths: 1 1 1 1 2
|
|
|
|
|
|
|
|
|
|
* - :rspan:`1` head / stub
|
|
|
|
|
- :cspan:`3` head 1.1-4
|
|
|
|
|
|
|
|
|
|
* - head 2.1
|
|
|
|
|
- head 2.2
|
|
|
|
|
- head 2.3
|
|
|
|
|
- head 2.4
|
|
|
|
|
|
|
|
|
|
* .. row body 1 / this is a comment
|
|
|
|
|
|
|
|
|
|
- row 1
|
|
|
|
|
- :rspan:`2` cell 1-3.1
|
|
|
|
|
- cell 1.2
|
|
|
|
|
- cell 1.3
|
|
|
|
|
- cell 1.4
|
|
|
|
|
|
|
|
|
|
* .. Comments and targets are allowed on *table-row* stage.
|
|
|
|
|
.. _`row body 2`:
|
|
|
|
|
|
|
|
|
|
- row 2
|
|
|
|
|
- cell 2.2
|
|
|
|
|
- :rspan:`1` :cspan:`1`
|
|
|
|
|
cell 2.3 with a span over
|
|
|
|
|
|
|
|
|
|
* col 3-4 &
|
|
|
|
|
* row 2-3
|
|
|
|
|
|
|
|
|
|
* - row 3
|
|
|
|
|
- cell 3.2
|
|
|
|
|
|
|
|
|
|
* - row 4
|
|
|
|
|
- cell 4.1
|
|
|
|
|
- cell 4.2
|
|
|
|
|
- cell 4.3
|
|
|
|
|
- cell 4.4
|
|
|
|
|
|
|
|
|
|
* - row 5
|
|
|
|
|
- cell 5.1 with automatic span to rigth end
|
|
|
|
|
|
|
|
|
|
* - row 6
|
|
|
|
|
- cell 6.1
|
|
|
|
|
- ..
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. admonition:: List table
|
|
|
|
|
:class: rst-example
|
|
|
|
|
|
|
|
|
|
.. flat-table:: ``flat-table`` example
|
|
|
|
|
:header-rows: 2
|
|
|
|
|
:stub-columns: 1
|
|
|
|
|
:widths: 1 1 1 1 2
|
|
|
|
|
|
|
|
|
|
* - :rspan:`1` head / stub
|
|
|
|
|
- :cspan:`3` head 1.1-4
|
|
|
|
|
|
|
|
|
|
* - head 2.1
|
|
|
|
|
- head 2.2
|
|
|
|
|
- head 2.3
|
|
|
|
|
- head 2.4
|
|
|
|
|
|
|
|
|
|
* .. row body 1 / this is a comment
|
|
|
|
|
|
|
|
|
|
- row 1
|
|
|
|
|
- :rspan:`2` cell 1-3.1
|
|
|
|
|
- cell 1.2
|
|
|
|
|
- cell 1.3
|
|
|
|
|
- cell 1.4
|
|
|
|
|
|
|
|
|
|
* .. Comments and targets are allowed on *table-row* stage.
|
|
|
|
|
.. _`row body 2`:
|
|
|
|
|
|
|
|
|
|
- row 2
|
|
|
|
|
- cell 2.2
|
|
|
|
|
- :rspan:`1` :cspan:`1`
|
|
|
|
|
cell 2.3 with a span over
|
|
|
|
|
|
|
|
|
|
* col 3-4 &
|
|
|
|
|
* row 2-3
|
|
|
|
|
|
|
|
|
|
* - row 3
|
|
|
|
|
- cell 3.2
|
|
|
|
|
|
|
|
|
|
* - row 4
|
|
|
|
|
- cell 4.1
|
|
|
|
|
- cell 4.2
|
|
|
|
|
- cell 4.3
|
|
|
|
|
- cell 4.4
|
|
|
|
|
|
|
|
|
|
* - row 5
|
|
|
|
|
- cell 5.1 with automatic span to rigth end
|
|
|
|
|
|
|
|
|
|
* - row 6
|
|
|
|
|
- cell 6.1
|
|
|
|
|
- ..
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
CSV table
|
|
|
|
|
---------
|
|
|
|
|
|
|
|
|
|
CSV table might be the choice if you want to include CSV-data from a outstanding
|
|
|
|
|
(build) process into your documentation.
|
|
|
|
|
|
|
|
|
|
.. code:: reST
|
|
|
|
|
|
|
|
|
|
.. csv-table:: CSV table example
|
|
|
|
|
:header: .. , Column 1, Column 2
|
|
|
|
|
:widths: 2 5 5
|
|
|
|
|
:stub-columns: 1
|
|
|
|
|
:file: csv_table.txt
|
|
|
|
|
|
|
|
|
|
Content of file ``csv_table.txt``:
|
|
|
|
|
|
|
|
|
|
.. literalinclude:: csv_table.txt
|
|
|
|
|
|
|
|
|
|
.. admonition:: CSV table
|
|
|
|
|
:class: rst-example
|
|
|
|
|
|
|
|
|
|
.. csv-table:: CSV table example
|
|
|
|
|
:header: .. , Column 1, Column 2
|
|
|
|
|
:widths: 3 5 5
|
|
|
|
|
:stub-columns: 1
|
|
|
|
|
:file: csv_table.txt
|
|
|
|
|
|
2019-12-21 16:13:38 +00:00
|
|
|
|
Templating
|
|
|
|
|
==========
|
|
|
|
|
|
|
|
|
|
.. sidebar:: Build environment
|
|
|
|
|
|
|
|
|
|
All *generic-doc* tasks are running in the :ref:`build environment <make
|
|
|
|
|
pyenv>`.
|
|
|
|
|
|
|
|
|
|
Templating is suitable for documentation which is created generic at the build
|
|
|
|
|
time. The sphinx-jinja_ extension evaluates jinja_ templates in the :ref:`build
|
2019-12-22 13:08:57 +00:00
|
|
|
|
environment <make pyenv>` (with searx modules installed). We use this e.g. to
|
|
|
|
|
build chapter: :ref:`engines generic`. Below the jinja directive from the
|
|
|
|
|
:origin:`docs/admin/engines.rst` is shown:
|
2019-12-21 16:13:38 +00:00
|
|
|
|
|
|
|
|
|
.. literalinclude:: ../admin/engines.rst
|
|
|
|
|
:language: reST
|
|
|
|
|
:start-after: .. _configured engines:
|
|
|
|
|
|
|
|
|
|
The context for the template is selected in the line ``.. jinja:: webapp``. In
|
|
|
|
|
sphinx's build configuration (:origin:`docs/conf.py`) the ``webapp`` context
|
|
|
|
|
points to the name space of the python module: ``webapp``.
|
|
|
|
|
|
|
|
|
|
.. code:: py
|
|
|
|
|
|
|
|
|
|
from searx import webapp
|
|
|
|
|
jinja_contexts = {
|
|
|
|
|
'webapp': dict(**webapp.__dict__)
|
|
|
|
|
}
|
|
|
|
|
|
2019-12-20 19:39:14 +00:00
|
|
|
|
|
2019-12-20 10:01:41 +00:00
|
|
|
|
|
2019-12-19 16:05:50 +00:00
|
|
|
|
.. _KISS: https://en.wikipedia.org/wiki/KISS_principle
|
2019-12-20 19:39:14 +00:00
|
|
|
|
|
2019-12-19 16:05:50 +00:00
|
|
|
|
.. _readability: https://docs.python-guide.org/writing/style/
|
|
|
|
|
.. _Sphinx-Primer:
|
|
|
|
|
http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
|
|
|
|
|
.. _reST: https://docutils.sourceforge.io/rst.html
|
|
|
|
|
.. _Sphinx Roles:
|
|
|
|
|
https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
|
|
|
|
|
.. _Sphinx: http://www.sphinx-doc.org
|
|
|
|
|
.. _`sphinx-doc FAQ`: http://www.sphinx-doc.org/en/stable/faq.html
|
|
|
|
|
.. _Sphinx markup constructs:
|
|
|
|
|
http://www.sphinx-doc.org/en/stable/markup/index.html
|
|
|
|
|
.. _`sphinx cross references`:
|
|
|
|
|
http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations
|
|
|
|
|
.. _sphinx.ext.extlinks:
|
|
|
|
|
https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
|
|
|
|
|
.. _intersphinx: http://www.sphinx-doc.org/en/stable/ext/intersphinx.html
|
|
|
|
|
.. _sphinx config: http://www.sphinx-doc.org/en/stable/config.html
|
|
|
|
|
.. _Sphinx's autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html
|
|
|
|
|
.. _Sphinx's Python domain:
|
|
|
|
|
http://www.sphinx-doc.org/en/stable/domains.html#the-python-domain
|
|
|
|
|
.. _Sphinx's C domain:
|
|
|
|
|
http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-c-constructs
|
|
|
|
|
.. _doctree:
|
|
|
|
|
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
|
2019-12-19 22:36:53 +00:00
|
|
|
|
.. _linuxdoc: https://return42.github.io/linuxdoc
|
2019-12-21 16:13:38 +00:00
|
|
|
|
.. _jinja: https://jinja.palletsprojects.com/
|
|
|
|
|
.. _sphinx-jinja: https://github.com/tardyp/sphinx-jinja
|
2019-12-20 11:10:43 +00:00
|
|
|
|
.. _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
|
2019-12-20 19:39:14 +00:00
|
|
|
|
|
|
|
|
|
.. _`Emacs Table Mode`: https://www.emacswiki.org/emacs/TableMode
|
|
|
|
|
.. _`Online Tables Generator`: http://www.tablesgenerator.com/text_tables
|
|
|
|
|
.. _`OASIS XML Exchange Table Model`: https://www.oasis-open.org/specs/tm9901.html
|