reStructuredText is an easy to read, what-you-see-is-what-you-get plainttext markup syntax and parser system. In other words reStructuredText is a lightweight markup language that is used in static
site generators like Sphinx. It contains robust tools for semantic markup, reusing content, and content filters for different kinds of outputs.
It’s also easily extendible using custom directives that you can create yourself, allowing you to satisfy a wide variety of documentation needs.
reStructuredText is useful for creating simple web pages, and for standalone documents.
Why use reStructuredText?
-------------------------
*************************
reStructuredText is a lightweight markup language, so it’s easier to read in plain-text format compared to heavier markup languages like DITA and other XML-based formats.
You can easily find text editors that render reStructuredText with syntax highlighting and live previews, without having to invest in complex tools. Compared to some other lightweight markup languages
like MarkDown, reStructuredText contains stronger semantic markup tools. Some writers also prefer reStructuredText because the markup standards are more well-defined compared to MarkDown.
Paragraphs in reStructuredText are blocks of text separated by at least one blank line. All lines in the paragraph must be indented by the same amount:
*Syntax*
.. code-block::
.. code-block:: console
* Use one asterisk (*text*) for italic
* Use two asterisks (**text**) for bold
...
...
@@ -44,7 +44,7 @@ Paragraphs in reStructuredText are blocks of text separated by at least one blan
* Use two backticks (``text``) for code sample
Headers
#######
=======
Headers are demarcated by non-alphanumeric characters like dashes, equal signs, or tildes. Use the same character for headers at the same level. The following creates a header:
...
...
@@ -58,43 +58,43 @@ Headers are demarcated by non-alphanumeric characters like dashes, equal signs,
*Syntax*
.. code-block::
.. code-block:: console
Heading one
===========
###########
Heading two
-----------
***********
Heading three
#############
=============
Heading four
************
------------
*Output*
Heading one
===========
###########
Heading two
-----------
***********
Heading three
#############
=============
Heading four
************
------------
List
####
====
For creating list just place an asterisk(*) or hyphen (-) at the start of a paragraph and indent continuation lines with one space. The same goes for numbered lists; they can also be autonumbered using a (#) sign:
*Syntax*
.. code-block::
.. code-block:: console
* This is a bulleted list.
* It has two items, the second
...
...
@@ -120,13 +120,13 @@ For creating list just place an asterisk(*) or hyphen (-) at the start of a para
Images
######
======
reST supports an image directive:
*Syntax*
.. code-block::
.. code-block:: console
.. figure:: /images/multi data.png
...
...
@@ -136,16 +136,16 @@ reST supports an image directive:
Tables
######
======
The "list-table" directive is used to create a table from data in a uniform two-level bullet list. "Uniform" means that each sublist (second-level list) must contain the same number of list items:
Internal linking is done via a special reST role provided by Sphinx, Cross-referencing syntax `<https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_.
Roles
-----
=====
Math
****
----
*Syntax*
.. code-block::gbv
.. code-block:: console
Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`
