@@ -88,19 +88,23 @@ Developer's POV: :origin:`docs/dev`
8888Basic inline markup
8989===================
9090
91−``*italics*`` -- *italics*
92− one asterisk for emphasis
91+.. sidebar:: Inline markup
9392
94−``**boldface**`` -- **boldface**
95− two asterisks for strong emphasis and
93+ - :ref:`reST roles`
94+ - :ref:`reST smart ref`
9695
97−````foo()```` -- ``foo()``
98− backquotes for code samples and literals.
96+Basic inline markup is done with asterisks and backquotes. If asterisks or
97+backquotes appear in running text and could be confused with inline markup
98+delimiters, they have to be escaped with a backslash (``\*pointer``).
9999
100−``\*foo is a pointer`` -- \*foo is a pointer
101− If asterisks or backquotes appear in running text and could be confused with
102− inline markup delimiters, they have to be escaped with a backslash (``\*foo is
103− a pointer``).
100+================================================ ==================== ========================
101+description rendered markup
102+================================================ ==================== ========================
103+one asterisk for emphasis *italics* ``*italics*``
104+two asterisks for strong emphasis **boldface** ``**boldface**``
105+backquotes for code samples and literals ``foo()`` ````foo()````
106+quote asterisks or backquotes \*foo is a pointer ``\*foo is a pointer``
107+================================================ ==================== ========================
104108
105109.. _reST basic structure:
106110
@@ -110,44 +114,82 @@ Basic article structure
110114The basic structure of an article makes use of heading adornments to markup
111115chapter, sections and subsections.
112116
113−#. ``=`` with overline for document title
114−#. ``=`` for chapters
115−#. ``-`` for sections
116−#. ``~`` for subsections
117−
118117.. _reST template:
119118
120−.. admonition:: reST template
121− :class: rst-example
119+reST template
120+-------------
122121
123− .. code:: reST
122+reST template for an simple article:
123+
124+.. code:: reST
125+
126+ .. _doc refname:
127+
128+ ==============
129+ Document title
130+ ==============
131+
132+ Lorem ipsum dolor sit amet, consectetur adipisici elit .. Further read
133+ :ref:`chapter refname`.
134+
135+ .. _chapter refname:
136+
137+ Chapter
138+ =======
139+
140+ Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
141+ aliquid ex ea commodi consequat ...
142+
143+ .. _section refname:
144+
145+ Section
146+ -------
124147
125− .. _document title:
148+ lorem ..
149+
150+ .. _subsection refname:
151+
152+ Subsection
153+ ~~~~~~~~~~
154+
155+ lorem ..
156+
157+
158+Headings
159+--------
160+
161+#. title - with overline for document title:
162+
163+ .. code:: reST
164+
165+ ==============
166+ Document title
167+ ==============
168+
169+
170+#. chapter - with anchor named ``anchor name``:
171+
172+ .. code:: reST
126173
127− ==============
128− Document title
129− ==============
174+ .. _anchor name:
130175
131− Lorem ipsum dolor sit amet, consectetur adipisici elit ..
132− Further read :ref:`chapter title`.
176+ Chapter
177+ =======
133178
134− .. _chapter title:
179+#. section
135180
136− Chapters
137− ========
181+ .. code:: reST
138182
139− Ut enim ad minim veniam, quis nostrud exercitation ullamco
140− laboris nisi ut aliquid ex ea commodi consequat ...
183+ Section
184+ -------
141185
142− Section
143− -------
186+#. subsection
144187
145− lorem ..
188+ .. code:: reST
146189
147− Subsection
148− ~~~~~~~~~~
190+ Subsection
191+ ~~~~~~~~~~
149192
150− lorem ..
151193
152194
153195Anchors & Links
@@ -179,18 +221,18 @@ To refer anchors use the `ref role`_ markup:
179221
180222.. code:: reST
181223
182− Visit chapter :ref:`reST anchor`.
183− Or set hyperlink text manualy :ref:`foo bar <reST anchor>`.
224+ Visit chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
225+ bar <reST anchor>`.
184226
185227.. admonition:: ``:ref:`` role
186228 :class: rst-example
187229
188− Visist chapter :ref:`reST anchor`
189− Or set hyperlink text manualy :ref:`foo bar <reST anchor>`.
230+ Visist chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
231+ bar <reST anchor>`.
190232
191233.. _reST ordinary ref:
192234
193−link ordinary URL
235+Link ordinary URL
194236-----------------
195237
196238If you need to reference external URLs use *named* hyperlinks to maintain
@@ -221,8 +263,8 @@ readability of reST sources. Here is a example taken from *this* article:
221263
222264.. _reST smart ref:
223265
224−smart references
225−----------------
266+Smart refs
267+----------
226268
227269With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
228270content becomes smart.
@@ -270,6 +312,8 @@ To list all anchors of the inventory (e.g. ``python``) use:
270312 $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
271313
272314
315+.. _reST roles:
316+
273317Roles
274318=====
275319
@@ -634,9 +678,24 @@ Further list blocks
634678Admonitions
635679===========
636680
637−Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
638−:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, ,
639−:dudir:`warning` and the generic :dudir:`admonition <admonitions>`.
681+Sidebar
682+-------
683+
684+Sidebar is an eye catcher, often used for admonitions pointing further stuff or
685+site effects. Here is the source of the sidebar :ref:`on top of this page <reST
686+primer>`.
687+
688+.. code:: reST
689+
690+ .. sidebar:: KISS_ and readability_
691+
692+ Instead of defining more and more roles, we at searx encourage our
693+ contributors to follow principles like KISS_ and readability_.
694+
695+Generic admonition
696+------------------
697+
698+The generic :dudir:`admonition <admonitions>` needs a title:
640699
641700.. code:: reST
642701
@@ -644,6 +703,21 @@ Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
644703
645704 lorem ipsum ..
646705
706+
707+.. admonition:: generic admonition title
708+
709+ lorem ipsum ..
710+
711+
712+Specific admonitions
713+--------------------
714+
715+Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
716+:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, and
717+:dudir:`warning` .
718+
719+.. code:: reST
720+
647721 .. hint::
648722
649723 lorem ipsum ..
@@ -657,10 +731,6 @@ Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
657731 lorem ipsum ..
658732
659733
660−.. admonition:: generic admonition title
661−
662− lorem ipsum ..
663−
664734.. hint::
665735
666736 lorem ipsum ..