@@ -88,19 +88,23 @@ Developer's POV: :origin:`docs/dev`
88Basic inline markup
88Basic inline markup
89===================
89===================
91−``*italics*`` -- *italics*
91+.. sidebar:: Inline markup
92− one asterisk for emphasis
94−``**boldface**`` -- **boldface**
93+ - :ref:`reST roles`
95− two asterisks for strong emphasis and
94+ - :ref:`reST smart ref`
97−````foo()```` -- ``foo()``
96+Basic inline markup is done with asterisks and backquotes. If asterisks or
98− backquotes for code samples and literals.
97+backquotes appear in running text and could be confused with inline markup
98+delimiters, they have to be escaped with a backslash (``\*pointer``).
100−``\*foo is a pointer`` -- \*foo is a pointer
100+================================================ ==================== ========================
101− If asterisks or backquotes appear in running text and could be confused with
101+description rendered markup
102− inline markup delimiters, they have to be escaped with a backslash (``\*foo is
102+================================================ ==================== ========================
103− a pointer``).
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+================================================ ==================== ========================
105.. _reST basic structure:
109.. _reST basic structure:
@@ -110,44 +114,82 @@ Basic article structure
110The basic structure of an article makes use of heading adornments to markup
114The basic structure of an article makes use of heading adornments to markup
111chapter, sections and subsections.
115chapter, sections and subsections.
113−#. ``=`` with overline for document title
114−#. ``=`` for chapters
115−#. ``-`` for sections
116−#. ``~`` for subsections
118.. _reST template:
117.. _reST template:
120−.. admonition:: reST template
119+reST template
121− :class: rst-example
120+-------------
122+reST template for an simple article:
123− .. code:: reST
124+.. code:: reST
132+ Lorem ipsum dolor sit amet, consectetur adipisici elit .. Further read
133+ :ref:`chapter refname`.
135+ .. _chapter refname:
140+ Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
141+ aliquid ex ea commodi consequat ...
143+ .. _section refname:
125− .. _document title:
148+ lorem ..
150+ .. _subsection refname:
161+#. title - with overline for document title:
170+#. chapter - with anchor named ``anchor name``:
127− ==============
174+ .. _anchor name:
131− Lorem ipsum dolor sit amet, consectetur adipisici elit ..
176+ Chapter
132− Further read :ref:`chapter title`.
177+ =======
134− .. _chapter title:
179+#. section
136− Chapters
181+ .. code:: reST
139− Ut enim ad minim veniam, quis nostrud exercitation ullamco
183+ Section
140− laboris nisi ut aliquid ex ea commodi consequat ...
184+ -------
142− Section
186+#. subsection
145− lorem ..
188+ .. code:: reST
147− Subsection
190+ Subsection
148− ~~~~~~~~~~
191+ ~~~~~~~~~~
153Anchors & Links
195Anchors & Links
@@ -179,18 +221,18 @@ To refer anchors use the `ref role`_ markup:
180.. code:: reST
222.. code:: reST
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
185.. admonition:: ``:ref:`` role
227.. admonition:: ``:ref:`` role
186 :class: rst-example
228 :class: rst-example
188− Visist chapter :ref:`reST anchor`
230+ Visist chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
189− Or set hyperlink text manualy :ref:`foo bar <reST anchor>`.
231+ bar <reST anchor>`.
191.. _reST ordinary ref:
233.. _reST ordinary ref:
193−link ordinary URL
235+Link ordinary URL
194-----------------
236-----------------
196If you need to reference external URLs use *named* hyperlinks to maintain
238If 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:
222.. _reST smart ref:
264.. _reST smart ref:
224−smart references
266+Smart refs
225−----------------
267+----------
227With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
269With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
228content becomes smart.
270content becomes smart.
@@ -270,6 +312,8 @@ To list all anchors of the inventory (e.g. ``python``) use:
270 $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
312 $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
@@ -634,9 +678,24 @@ Further list blocks
634Admonitions
678Admonitions
635===========
679===========
637−Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
681+Sidebar
638−:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, ,
682+-------
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
690+ .. sidebar:: KISS_ and readability_
692+ Instead of defining more and more roles, we at searx encourage our
693+ contributors to follow principles like KISS_ and readability_.
639−:dudir:`warning` and the generic :dudir:`admonition <admonitions>`.
698+The generic :dudir:`admonition <admonitions>` needs a title:
641.. code:: reST
700.. code:: reST
@@ -644,6 +703,21 @@ Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
645 lorem ipsum ..
704 lorem ipsum ..
707+.. admonition:: generic admonition title
715+Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
716+:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, and
647 .. hint::
721 .. hint::
649 lorem ipsum ..
723 lorem ipsum ..
@@ -657,10 +731,6 @@ Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
657 lorem ipsum ..
731 lorem ipsum ..
660−.. admonition:: generic admonition title
666 lorem ipsum ..
736 lorem ipsum ..