docs: reST-primer continued proofreading (WIP)

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
This commit is contained in:
Markus Heiser 2019-12-20 17:47:24 +01:00
parent ae7cb5937e
commit b201f84595
1 changed files with 119 additions and 49 deletions

View File

@ -88,19 +88,23 @@ Developer's POV: :origin:`docs/dev`
Basic inline markup Basic inline markup
=================== ===================
``*italics*`` -- *italics* .. sidebar:: Inline markup
one asterisk for emphasis
``**boldface**`` -- **boldface** - :ref:`reST roles`
two asterisks for strong emphasis and - :ref:`reST smart ref`
````foo()```` -- ``foo()`` Basic inline markup is done with asterisks and backquotes. If asterisks or
backquotes for code samples and literals. backquotes appear in running text and could be confused with inline markup
delimiters, they have to be escaped with a backslash (``\*pointer``).
``\*foo is a pointer`` -- \*foo is a pointer ================================================ ==================== ========================
If asterisks or backquotes appear in running text and could be confused with description rendered markup
inline markup delimiters, they have to be escaped with a backslash (``\*foo is ================================================ ==================== ========================
a pointer``). 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: .. _reST basic structure:
@ -110,44 +114,82 @@ Basic article structure
The basic structure of an article makes use of heading adornments to markup The basic structure of an article makes use of heading adornments to markup
chapter, sections and subsections. chapter, sections and subsections.
#. ``=`` with overline for document title
#. ``=`` for chapters
#. ``-`` for sections
#. ``~`` for subsections
.. _reST template: .. _reST template:
.. admonition:: reST template reST template
:class: rst-example -------------
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 .. code:: reST
.. _document title: .. _anchor name:
============== Chapter
Document title =======
==============
Lorem ipsum dolor sit amet, consectetur adipisici elit .. #. section
Further read :ref:`chapter title`.
.. _chapter title: .. code:: reST
Chapters Section
======== -------
Ut enim ad minim veniam, quis nostrud exercitation ullamco #. subsection
laboris nisi ut aliquid ex ea commodi consequat ...
Section .. code:: reST
-------
lorem .. Subsection
~~~~~~~~~~
Subsection
~~~~~~~~~~
lorem ..
Anchors & Links Anchors & Links
@ -179,18 +221,18 @@ To refer anchors use the `ref role`_ markup:
.. code:: reST .. code:: reST
Visit chapter :ref:`reST anchor`. Visit chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
Or set hyperlink text manualy :ref:`foo bar <reST anchor>`. bar <reST anchor>`.
.. admonition:: ``:ref:`` role .. admonition:: ``:ref:`` role
:class: rst-example :class: rst-example
Visist chapter :ref:`reST anchor` Visist chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
Or set hyperlink text manualy :ref:`foo bar <reST anchor>`. bar <reST anchor>`.
.. _reST ordinary ref: .. _reST ordinary ref:
link ordinary URL Link ordinary URL
----------------- -----------------
If you need to reference external URLs use *named* hyperlinks to maintain If 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:
.. _reST smart ref: .. _reST smart ref:
smart references Smart refs
---------------- ----------
With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
content becomes smart. content becomes smart.
@ -270,6 +312,8 @@ To list all anchors of the inventory (e.g. ``python``) use:
$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
.. _reST roles:
Roles Roles
===== =====
@ -634,9 +678,24 @@ Further list blocks
Admonitions Admonitions
=========== ===========
Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`, Sidebar
:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, , -------
:dudir:`warning` and the generic :dudir:`admonition <admonitions>`.
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 .. code:: reST
@ -644,6 +703,21 @@ Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
lorem ipsum .. 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:: .. hint::
lorem ipsum .. lorem ipsum ..
@ -657,10 +731,6 @@ Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
lorem ipsum .. lorem ipsum ..
.. admonition:: generic admonition title
lorem ipsum ..
.. hint:: .. hint::
lorem ipsum .. lorem ipsum ..