mirrors/searxng
1
0
Fork 0
mirror of https://github.com/searxng/searxng.git synced 2024-06-02 21:39:22 +00:00
Code Issues Projects Releases Wiki Activity
searxng/docs/dev/reST.rst
Markus Heiser b82f61f704 doc: reST primer -- describe admonitions & customize their CSS 
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
2019-12-20 11:01:41 +01:00

19 KiB
Raw Blame History

reST primer

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 github.io <.>.

The sources of Searx's documentation are located at docs. Run make docs-live <make docs-live> to build HTML while editing.

Contents

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].

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 (docs) folder we have three sections (and the blog folder), each dedicate to a different group of audience.

User's POV: docs/user

A typical user knows about search engines and might have heard about meta crawlers and privacy.

Admin's POV: 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: 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), describe chronological order matters, describe it. Name the out-of-limits condition and all the side effects a external developer will not know.

Basic inline markup

*italics* -- italics

one asterisk for emphasis

**boldface** -- boldface

two asterisks for strong emphasis and

foo() -- foo()

backquotes for code samples and literals.

\*foo is a pointer -- *foo is a pointer

If asterisks or backquotes appear in running text and could be confused with inline markup delimiters, they have to be escaped with a backslash (\*foo is a pointer).

Basic article structure

The basic structure of an article makes use of heading adornments to markup chapter, sections and subsections.

  1. = with overline for document title
  2. = for chapters
  3. - for sections
  4. ~ for subsections

reST template

.. _document title:

==============
Document title
==============

Lorem ipsum dolor sit amet, consectetur adipisici elit ..
Further read :ref:`chapter title`.

.. _chapter title:

Chapters
========

Ut enim ad minim veniam, quis nostrud exercitation ullamco
laboris nisi ut aliquid ex ea commodi consequat ...

Section
-------

lorem ..

Subsection
~~~~~~~~~~

lorem ..

Anchors & Links

Anchors

To refer a point in the documentation a anchor is needed. The 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:

.. _reST anchor:

Anchors
-------

To refer a point in the documentation a anchor is needed ...

To refer anchors use the ref role markup:

Visit chapter :ref:`reST anchor`.
Or set hyperlink text manualy :ref:`foo bar <reST anchor>`.

:ref: role

Visist chapter reST anchor Or set hyperlink text manualy foo bar <reST anchor>.

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:

.. _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>`__.

Named hyperlink

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.

smart references

With the power of sphinx.ext.extlinks and intersphinx referencing external content becomes smart.

refer ... rendered example markup
:rstrfc 822 :rfc:`822`

:rstpep sphinx.ext.extlinks

8

:pep:`8`
--------------------------- ----------------------------------- ------------------------------------
project's wiki article Searx-instances :wiki:`Searx-instances`
to docs public URL dev/reST.html :docs:`dev/reST.html`
files & folders origin docs/dev/reST.rst :origin:`docs/dev/reST.rst`
pull request 1756 :pull:`1756`
patch af2cae6 :patch:`af2cae6`
PyPi package searx :pypi:`searx`

manual page man intersphinx

bash

:man:`bash`
--------------------------- ----------------------------------- ------------------------------------
external anchor python:and :ref:`python:and`
external doc anchor jinja:templates :doc:`jinja:templates`
python code object :pydatetime.datetime :py:obj:`datetime.datetime`
flask code object :pyflask.Flask :py:obj:`flask.Flask`

Intersphinx is configured in docs/conf.py:

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:

$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv

Roles

A custom interpreted text role (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 syntax is :rolename:`content`.

role rendered example markup
:rstguilabel &Cancel :guilabel:`&Cancel`
:rstkbd C-x C-f :kbd:`C-x C-f`
:rstmenuselection Open --> File :menuselection:`Open --> File`
:rstdownload this file <reST.rst> :download:`this file <reST.rst>`
:rstmath a2 + b2 = c2 :math:`a^2 + b^2 = c^2`
:rstref svg image example :ref:`svg image example`
:rstcommand ls -la :command:`ls -la`
emphasis italic :emphasis:`italic`
strong bold :strong:`bold`
literal foo() :literal:`foo()`
subscript H2O H\ :sub:`2`\ O
superscript E = mc2 E = mc\ :sup:`2`
title-reference Time :title:`Time`

Refer to Sphinx Roles for roles added by Sphinx.

Figures & Images

Searx's sphinx setup includes: 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 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 (svg_image_example):

.. _svg image example:

.. kernel-figure:: svg_image.svg
   :alt: simple SVG image

   SVG image example

svg_image.svg

SVG image example

DOT files (aka Graphviz)

The kernel figure (and image) directive support DOT formated files, see

A simple example (hello_dot_file):

.. kernel-figure:: hello.dot
   :alt: hello world

   DOT's hello world example

hello.dot

hello.dot

DOT's hello world example

kernel-render DOT

Embed render markups (or languages) like Graphviz's DOT is provided by the kernel-render directives.

.. kernel-render:: DOT markup
   :alt: foobar digraph
   :caption: Embedded **DOT** (Graphviz) code

   digraph foo {
     "bar" -> "baz";
   }

How this will be rendered depends on the installed tools. If Graphviz is installed, you will see an vector image. If not the raw markup is inserted as literal-block (hello_dot_render).

DOT markup

DOT

digraph foo {

"bar" -> "baz";

}

The render directive has all the options known from the figure directive, plus option caption. If caption has a value, a figure node is inserted. If not, a image node is inserted. A caption is also needed, if you want to refer it (hello_svg_render).

kernel-render SVG

.. kernel-render:: SVG markup
   :caption: Embedded **SVG** markup
   :alt: so-nw-arrow

SVG markup

SVG

<?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>

List markups

Bullet list

List markup (ref <bullet-lists>) is simple:

- 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.

bullet list

  • 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.
  1. This is a numbered list.
  2. It has two items too.

Definition list

definition term

Note that the term cannot have more than one line of text.

Definition lists (ref <definition-lists>) are created as follows:

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.

definition list

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 (ref <block-quotes>) are created by just indenting them more than the surrounding paragraphs. Line blocks (ref <line-blocks>) are a way of preserving line breaks:

normal paragraph ...
lorem ipsum.

   Quoted paragraph ...
   lorem ipsum.

| These lines are
| broken exactly like in
| the source file.

Quoted paragraph and line block

normal paragraph ... lorem ipsum.

Quoted paragraph ... lorem ipsum.

These lines are
broken exactly like in
the source file.

Field Lists

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:

:fieldname: Field content
:foo:       first paragraph in field foo

        second paragraph in field foo

:bar:       Field content

Field List

fieldname

Field content

foo

first paragraph in field foo

second paragraph in field foo

bar

Field content

They are commonly used in Python documentation:

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 (ref <field-lists>, with caveats noted in reST field list)
  • option lists (ref <option-lists>)
  • quoted literal blocks (ref <quoted-literal-blocks>)
  • doctest blocks (ref <doctest-blocks>)

Admonitions

Admonitions: hint, note, tip attention, caution, danger, error, , important, , warning and the generic admonition <admonitions>.

.. admonition:: generic admonition title

   lorem ipsum ..

.. hint::

   lorem ipsum ..

.. note::

   lorem ipsum ..

.. warning::

   lorem ipsum ..

generic admonition title

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 ..