mirror of https://github.com/searxng/searxng.git
docs: reST-primer continued proofreading (WIP)
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
This commit is contained in:
Markus Heiser
parent
ae7cb5937e
commit
b201f84595
|
|
@ -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 ..
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue