|
|
@@ -0,0 +1,1428 @@
|
|
|
+.. _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 <.>`. For build prerequisites read
|
|
|
+:ref:`docs build`.
|
|
|
+
|
|
|
+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
|
|
|
+
|
|
|
+ - Sphinx-Primer_
|
|
|
+ - `Sphinx markup constructs`_
|
|
|
+ - reST_, docutils_, `docutils FAQ`_
|
|
|
+ - Sphinx_, `sphinx-doc FAQ`_
|
|
|
+ - `sphinx config`_, doctree_
|
|
|
+ - `sphinx cross references`_
|
|
|
+ - linuxdoc_
|
|
|
+ - intersphinx_
|
|
|
+ - sphinx-jinja_
|
|
|
+ - `Sphinx's autodoc`_
|
|
|
+ - `Sphinx's Python domain`_, `Sphinx's C domain`_
|
|
|
+ - SVG_, ImageMagick_
|
|
|
+ - DOT_, `Graphviz's dot`_, Graphviz_
|
|
|
+
|
|
|
+
|
|
|
+.. 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
|
|
|
+ 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:
|
|
|
+
|
|
|
+Basic inline markup
|
|
|
+===================
|
|
|
+
|
|
|
+.. sidebar:: Inline markup
|
|
|
+
|
|
|
+ - :ref:`reST roles`
|
|
|
+ - :ref:`reST smart ref`
|
|
|
+
|
|
|
+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``).
|
|
|
+
|
|
|
+.. 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``
|
|
|
+ ================================================ ==================== ========================
|
|
|
+
|
|
|
+.. _reST basic structure:
|
|
|
+
|
|
|
+Basic article structure
|
|
|
+=======================
|
|
|
+
|
|
|
+The basic structure of an article makes use of heading adornments to markup
|
|
|
+chapter, sections and subsections.
|
|
|
+
|
|
|
+.. _reST template:
|
|
|
+
|
|
|
+reST template
|
|
|
+-------------
|
|
|
+
|
|
|
+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
|
|
|
+ -------
|
|
|
+
|
|
|
+ lorem ..
|
|
|
+
|
|
|
+ .. _subsection refname:
|
|
|
+
|
|
|
+ Subsection
|
|
|
+ ~~~~~~~~~~
|
|
|
+
|
|
|
+ lorem ..
|
|
|
+
|
|
|
+
|
|
|
+Headings
|
|
|
+--------
|
|
|
+
|
|
|
+#. title - with overline for document title:
|
|
|
+
|
|
|
+ .. code:: reST
|
|
|
+
|
|
|
+ ==============
|
|
|
+ Document title
|
|
|
+ ==============
|
|
|
+
|
|
|
+
|
|
|
+#. chapter - with anchor named ``anchor name``:
|
|
|
+
|
|
|
+ .. code:: reST
|
|
|
+
|
|
|
+ .. _anchor name:
|
|
|
+
|
|
|
+ Chapter
|
|
|
+ =======
|
|
|
+
|
|
|
+#. section
|
|
|
+
|
|
|
+ .. code:: reST
|
|
|
+
|
|
|
+ Section
|
|
|
+ -------
|
|
|
+
|
|
|
+#. subsection
|
|
|
+
|
|
|
+ .. code:: reST
|
|
|
+
|
|
|
+ Subsection
|
|
|
+ ~~~~~~~~~~
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+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
|
|
|
+
|
|
|
+ Visit chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
|
|
|
+ bar <reST anchor>`.
|
|
|
+
|
|
|
+.. admonition:: ``:ref:`` role
|
|
|
+ :class: rst-example
|
|
|
+
|
|
|
+ Visist chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
|
|
|
+ bar <reST anchor>`.
|
|
|
+
|
|
|
+.. _reST ordinary ref:
|
|
|
+
|
|
|
+Link ordinary URL
|
|
|
+-----------------
|
|
|
+
|
|
|
+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:
|
|
|
+
|
|
|
+Smart refs
|
|
|
+----------
|
|
|
+
|
|
|
+With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
|
|
|
+content becomes smart.
|
|
|
+
|
|
|
+.. 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```
|
|
|
+ ========================== ================================== ====================================
|
|
|
+
|
|
|
+
|
|
|
+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),
|
|
|
+ "jinja": ("https://jinja.palletsprojects.com/", None),
|
|
|
+ "linuxdoc" : ("https://return42.github.io/linuxdoc/", None),
|
|
|
+ "sphinx" : ("https://www.sphinx-doc.org/en/master/", None),
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+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
|
|
|
+
|
|
|
+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:
|
|
|
+
|
|
|
+Roles
|
|
|
+=====
|
|
|
+
|
|
|
+.. sidebar:: Further reading
|
|
|
+
|
|
|
+ - `Sphinx Roles`_
|
|
|
+ - :doc:`sphinx:usage/restructuredtext/domains`
|
|
|
+
|
|
|
+
|
|
|
+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 markup is one of:
|
|
|
+
|
|
|
+.. code:: reST
|
|
|
+
|
|
|
+ :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>```
|
|
|
+ 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```
|
|
|
+ ========================== ================================== ====================================
|
|
|
+
|
|
|
+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`. 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 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`` (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
|
|
|
+
|
|
|
+ .. _svg image example:
|
|
|
+
|
|
|
+ .. kernel-figure:: svg_image.svg
|
|
|
+ :alt: 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: SVG image example
|
|
|
+
|
|
|
+ Simple SVG image.
|
|
|
+
|
|
|
+To refer the figure, a caption block is needed: :ref:`svg image example`.
|
|
|
+
|
|
|
+DOT files (aka Graphviz)
|
|
|
+------------------------
|
|
|
+
|
|
|
+With :ref:`linuxdoc:kernel-figure` reST support for **DOT** formatted files is
|
|
|
+given.
|
|
|
+
|
|
|
+- `Graphviz's dot`_
|
|
|
+- DOT_
|
|
|
+- Graphviz_
|
|
|
+
|
|
|
+A simple example is shown in :ref:`dot file example`:
|
|
|
+
|
|
|
+.. code:: reST
|
|
|
+
|
|
|
+ .. _dot file example:
|
|
|
+
|
|
|
+ .. kernel-figure:: hello.dot
|
|
|
+ :alt: hello world
|
|
|
+
|
|
|
+ DOT's hello world example
|
|
|
+
|
|
|
+.. admonition:: hello.dot
|
|
|
+ :class: rst-example
|
|
|
+
|
|
|
+ .. _dot file 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
|
|
|
+:ref:`linuxdoc:kernel-render` directive. A simple example of embedded DOT_ is
|
|
|
+shown in figure :ref:`dot render example`:
|
|
|
+
|
|
|
+.. code:: reST
|
|
|
+
|
|
|
+ .. _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`.
|
|
|
+
|
|
|
+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
|
|
|
+---------------------
|
|
|
+
|
|
|
+A simple example of embedded SVG_ is shown in figure :ref:`svg render example`:
|
|
|
+
|
|
|
+.. code:: reST
|
|
|
+
|
|
|
+ .. _svg render example:
|
|
|
+
|
|
|
+ .. kernel-render:: SVG
|
|
|
+ :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:: kernel-render SVG
|
|
|
+ :class: rst-example
|
|
|
+
|
|
|
+ .. _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>
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+.. _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.
|
|
|
+
|
|
|
+
|
|
|
+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
|
|
|
+---------------
|
|
|
+
|
|
|
+.. sidebar:: Note ..
|
|
|
+
|
|
|
+ - the term cannot have more than one line of text
|
|
|
+
|
|
|
+ - there is **no blank line between term and definition block** // this
|
|
|
+ distinguishes definition lists (:duref:`ref <definition-lists>`) from block
|
|
|
+ quotes (:duref:`ref <block-quotes>`).
|
|
|
+
|
|
|
+Each definition list (:duref:`ref <definition-lists>`) item contains a term,
|
|
|
+optional classifiers and a definition. A term is a simple one-line word or
|
|
|
+phrase. Optional classifiers may follow the term on the same line, each after
|
|
|
+an inline ' : ' (**space, colon, space**). A definition is a block indented
|
|
|
+relative to the term, and may contain multiple paragraphs and other body
|
|
|
+elements. There may be no blank line between a term line and a definition block
|
|
|
+(*this distinguishes definition lists from block quotes*). Blank lines are
|
|
|
+required before the first and after the last definition list item, but are
|
|
|
+optional in-between.
|
|
|
+
|
|
|
+Definition lists are created as follows:
|
|
|
+
|
|
|
+.. code:: reST
|
|
|
+
|
|
|
+ term 1 (up to a line of text)
|
|
|
+ Definition 1.
|
|
|
+
|
|
|
+ See the typo : this line is not a term!
|
|
|
+
|
|
|
+ And this is not term's definition. **There is a blank line** in between
|
|
|
+ the line above and this paragraph. That's why this paragraph is taken as
|
|
|
+ **block quote** (:duref:`ref <block-quotes>`) and not as term's definition!
|
|
|
+
|
|
|
+ term 2
|
|
|
+ Definition 2, paragraph 1.
|
|
|
+
|
|
|
+ Definition 2, paragraph 2.
|
|
|
+
|
|
|
+ term 3 : classifier
|
|
|
+ Definition 3.
|
|
|
+
|
|
|
+ term 4 : classifier one : classifier two
|
|
|
+ Definition 4.
|
|
|
+
|
|
|
+.. admonition:: definition list
|
|
|
+ :class: rst-example
|
|
|
+
|
|
|
+ term 1 (up to a line of text)
|
|
|
+ Definition 1.
|
|
|
+
|
|
|
+ See the typo : this line is not a term!
|
|
|
+
|
|
|
+ And this is not term's definition. **There is a blank line** in between
|
|
|
+ the line above and this paragraph. That's why this paragraph is taken as
|
|
|
+ **block quote** (:duref:`ref <block-quotes>`) and not as term's definition!
|
|
|
+
|
|
|
+
|
|
|
+ term 2
|
|
|
+ Definition 2, paragraph 1.
|
|
|
+
|
|
|
+ Definition 2, paragraph 2.
|
|
|
+
|
|
|
+ term 3 : classifier
|
|
|
+ Definition 3.
|
|
|
+
|
|
|
+ term 4 : classifier one : classifier two
|
|
|
+
|
|
|
+
|
|
|
+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
|
|
|
+
|
|
|
+ second paragraph in field foo
|
|
|
+
|
|
|
+ :bar: Field content
|
|
|
+
|
|
|
+.. admonition:: Field List
|
|
|
+ :class: rst-example
|
|
|
+
|
|
|
+ :fieldname: Field content
|
|
|
+ :foo: first paragraph in field foo
|
|
|
+
|
|
|
+ second paragraph in field foo
|
|
|
+
|
|
|
+ :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>`)
|
|
|
+
|
|
|
+
|
|
|
+Admonitions
|
|
|
+===========
|
|
|
+
|
|
|
+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:
|
|
|
+
|
|
|
+.. code:: reST
|
|
|
+
|
|
|
+ .. admonition:: generic admonition title
|
|
|
+
|
|
|
+ lorem ipsum ..
|
|
|
+
|
|
|
+
|
|
|
+.. 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
|
|
|
+
|
|
|
+ .. 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 ..
|
|
|
+
|
|
|
+
|
|
|
+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
|
|
|
+
|
|
|
+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
|
|
|
+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:
|
|
|
+
|
|
|
+.. 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__)
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+Tabbed views
|
|
|
+============
|
|
|
+
|
|
|
+.. _sphinx-tabs: https://github.com/djungelorm/sphinx-tabs
|
|
|
+.. _basic-tabs: https://github.com/djungelorm/sphinx-tabs#basic-tabs
|
|
|
+.. _group-tabs: https://github.com/djungelorm/sphinx-tabs#group-tabs
|
|
|
+.. _code-tabs: https://github.com/djungelorm/sphinx-tabs#code-tabs
|
|
|
+
|
|
|
+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_. 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
|
|
|
+
|
|
|
+ In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
|
|
|
+ is shown.
|
|
|
+
|
|
|
+ .. math::
|
|
|
+ :label: schroedinger general
|
|
|
+
|
|
|
+ \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
|
|
|
+ \hat{H} |\,\psi (t) \rangle.
|
|
|
+
|
|
|
+.. admonition:: LaTeX math equation
|
|
|
+ :class: rst-example
|
|
|
+
|
|
|
+ In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
|
|
|
+ is shown.
|
|
|
+
|
|
|
+ .. math::
|
|
|
+ :label: schroedinger general
|
|
|
+
|
|
|
+ \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
|
|
|
+ \hat{H} |\,\psi (t) \rangle.
|
|
|
+
|
|
|
+
|
|
|
+The next example shows the difference of ``\tfrac`` (*textstyle*) and ``\dfrac``
|
|
|
+(*displaystyle*) used in a inline markup or another fraction.
|
|
|
+
|
|
|
+.. code:: reST
|
|
|
+
|
|
|
+ ``\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}`
|
|
|
+
|
|
|
+.. admonition:: Line spacing
|
|
|
+ :class: rst-example
|
|
|
+
|
|
|
+ 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.
|
|
|
+
|
|
|
+ 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
|
|
|
+
|
|
|
+.. _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
|
|
|
+.. _linuxdoc: https://return42.github.io/linuxdoc
|
|
|
+.. _jinja: https://jinja.palletsprojects.com/
|
|
|
+.. _sphinx-jinja: https://github.com/tardyp/sphinx-jinja
|
|
|
+.. _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
|
|
|
+
|
|
|
+.. _`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
|
Markus Heiser
