.. _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 ` 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'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 ` 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 `. .. admonition:: ``:ref:`` role :class: rst-example Visist chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo bar `. .. _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 `__. .. 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 `__. .. _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 .. _reST roles: Roles ===== .. sidebar:: Further reading - `Sphinx Roles`_ - :doc:`sphinx:usage/restructuredtext/domains` A *custom interpreted text role* (:duref:`ref `) 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 ` .. 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 ` ``:download:`this file ``` :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``` ========================== ================================== ==================================== Figures & Images ================ .. sidebar:: Image processing With the directives from :ref:`linuxdoc ` the build process is flexible. To get best results in the generated output format, install ImageMagick_ and Graphviz_. Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scalable here means; scalable in sense of the build process. Normally in absence of a converter tool, the build process will break. From the authors POV 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 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 `. 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 .. admonition:: kernel-render SVG :class: rst-example .. _svg render example: .. kernel-render:: SVG :caption: Embedded **SVG** markup :alt: so-nw-arrow .. _reST lists: List markups ============ Bullet list ----------- List markup (:duref:`ref `) 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 `) 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 `) are created by just indenting them more than the surrounding paragraphs. Line blocks (:duref:`ref `) 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 `, with caveats noted in :ref:`reST field list`) - option lists (:duref:`ref `) - quoted literal blocks (:duref:`ref `) - doctest blocks (:duref:`ref `) 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 `. .. 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 ` 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 ` allow *colspan* but not *rowspan*. If your table need some metadata (e.g. a title) you need to add the ``.. table:: directive`` :dudir:`(ref) ` 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 ` 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 `. 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 `). .. 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 .. _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 .. _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