.. _rst: ¶
¶
================ ¶
reStructuredText ¶
================ ¶
¶
.. contents:: Contents ¶
¶
:Abstract ¶
======== ¶
: reStructuredText (reST, ReST, rst) is the superior lightweight markup language designed to be both (a) processable by machines (Denigma) and (b) easy readable by humans. ¶
¶
In its essence its just plain-text that uses simple and intuitive construct to indicate structure of a document. ¶
¶
¶
Introduction ¶
============ ¶
reStructuredText (reST) provides an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. There are some simple rules to follow: ¶
¶
* rst is like python, sensitive to indentation ¶
* blank lines are separated by blank lines ¶
¶
Title/Headings:/Sections ¶
============================ ¶
To create titles, headings and sections structure either underline or under and overline it:: ¶
¶
##### ¶
Title ¶
##### ¶
¶
Header ¶
====== ¶
¶
Subsection header ¶
----------------- ¶
¶
The title is unique and is usually defined at the very beginning (that's why it is omitted here): ¶
¶
Header ¶
====== ¶
¶
Subsection header ¶
----------------- ¶
¶
|Just follow to simple rules: ¶
¶
* The length of an underline must at least be as long as the header itself ¶
* If under and overline are used, their length mus be identical ¶
¶
There is not heading levels assigned to defined characters, the structure is simply defined from succession of headings. Though, it is recommended to stick to a certain convention throughout a project. ¶
¶
Lists: ¶
======= ¶
Lists are very simple an intuitive implemented and they come in different flavours. ¶
¶
Bullet & Enumerate ¶
------------------ ¶
¶
.. sourcecode:: rest ¶
¶
- A bullet list item ¶
- Second item ¶
¶
- A sub item ¶
¶
- Third item ¶
¶
¶
- A bullet list item ¶
- Second item ¶
¶
- A sub item ¶
¶
- Third item ¶
¶
¶
.. sourcecode:: rest ¶
¶
1) An enumerated list item ¶
2) Second item ¶
¶
a) Sub item ¶
¶
i) Sub-sub item ¶
¶
3) Third item which uses ¶
two lines (note indention). ¶
¶
1) An enumerated list item ¶
2) Second item ¶
¶
a) Sub item ¶
¶
i) Sub-sub item ¶
¶
3) Third item which uses ¶
two lines (note indention). ¶
¶
Auto-Numbered ¶
------------- ¶
¶
.. sourcecode:: rest ¶
¶
#) Another enumerated list item ¶
#) Second item ¶
¶
#) Another enumerated list item ¶
#) Second item ¶
¶
|Field ¶
----- ¶
A field list allows to simply create some fields with following text being intended: ¶
¶
.. sourcecode:: rest ¶
¶
:Research: About understanding nature. ¶
:Programming: Enables to automate information technologies. ¶
:Design: Requires creativity and innovation. ¶
¶
:Research: About understanding nature. ¶
:Programming: Enables to automate information technologies. ¶
:Design: Requires creativity and innovation. ¶
¶
Definition ¶
---------- ¶
An alternative is list definition: ¶
¶
.. sourcecode:: rest ¶
¶
Research ¶
About understanding nature. ¶
Programming ¶
Enables to automate information technologies. ¶
Design ¶
Requires creativity and innovation. ¶
¶
Research ¶
About understanding nature. ¶
Programming ¶
Enables to automate information technologies. ¶
Design ¶
Requires creativity and innovation. ¶
¶
**Images:** ¶
====== ¶
¶
.. sourcecode:: rest ¶
¶
.. image:: http://dgallery.s3.amazonaws.com/rst.png &para]
¶
.. image:: http://dgallery.s3.amazonaws.com/rst.png &para]
¶
|---- ¶
¶
.. sourcecode:: rest ¶
¶
.. image:: http://dgallery.s3.amazonaws.com/denigma_pos.png &para]
:width: 200px ¶
**N :height: 100px ¶
:align: center ¶
:alt: Alternative text ¶
¶
¶
.. image:: http://dgallery.s3.amazonaws.com/denigma_pos.png &para]
:width: 200px ¶
:height: 100px ¶
:align: center ¶
:alt: Alternative text ¶
¶
¶
Figures ¶
======= ¶
¶
.. sourcecode:: rest ¶
¶
.. figure:: http://dgallery.s3.amazonaws.com/denigma_pos.png ¶
:width: 200px ¶
:height: 100px ¶
:align: center ¶
:alt: Alternative text ¶
:figclass: align-center ¶
¶
Figures are like images but with a caption ¶
¶
and anything else can be added to it ¶
¶
.. sourcecode:: python ¶
¶
import image ¶
¶
.. figure:: http://dgallery.s3.amazonaws.com/denigma_pos.png &para]
:width: 200px ¶
:height: 100px ¶
:align: center ¶
:alt: Alternative text ¶
:figclass: align-center ¶
¶
**Figures are like images but with a caption ¶
¶
and anything else can be added to it ¶
¶
.. sourcecode:: python ¶
¶
import image ¶
¶
Comments ¶
======== ¶
Comments are marked with simple two dots: ¶
¶
.. sourcecode:: rest ¶
¶
.. comments ¶
¶
Links ¶
======= ¶
There are basically three types of links in rst: ¶
#. `External links`_ (urls) ¶
#. `Implicit links`_ to title/headers ¶
#. `Explicit links`_ to specific-defined elements (e.g. to refer to external titles) ¶
¶
External links ¶
-------------- ¶
To create a link to a website, the synthax is the following: ¶
¶
.. sourcecode:: rest ¶
¶
`<http://www.denigma.de&gt]`_ ¶
¶
This appears as `<http://www.denigma.de&gt]`_. An optional label can be defined too: ¶
¶
.. sourcecode:: rest ¶
¶
`Digital enigma < href='http://www.denigma.de&gt'>http://www.denigma.de&gt]`_ ¶
¶
That renders into `Digital enigma <http://www.denigma.de&gt]`_ ¶
¶
¶
Implicit links ¶
-------------- ¶
Every title/header is a hyperlink. A link to a section is just its name with in quotes followed by underscore: ¶
¶
.. sourcecode:: rest ¶
¶
`Explicit links`_ ¶
¶
¶
Explicit links ¶
-------------- ¶
A link can be explicitly established. For example in this data entry a explicit link rst was generated at the very top which is specified by: ¶
¶
.. sourcecode:: rest ¶
¶
.. _rst: ¶
¶
¶
It can be referred to it in two ways: ¶
¶
1. simple: ¶
¶
.. sourcecode:: rest ¶
¶
rst_ ¶
¶
2. ref as role: ¶
¶
:ref:``rst`` ¶
¶
With the former the link appears as rst_, whereas with the latter the first section's name after specifying the link is used and it would appear as :ref:`rst` (reStructuredText in theory). Note the latter works only with Sphinx, but can even establish cross-document links. ¶
¶
Named links ¶
----------- ¶
¶
.. sourcecode:: rest ¶
¶
A sentence with links to denigma_ and the `reStructured Text reference`_. ¶
¶
.. _denigma: http://www.denigma.de &para]
.. _`reStructured Text reference`: http://docutils.sourceforge.net/docs/user/rst/quickref.html= ¶
¶
A sentence with links to denigma_ and the `reStructured Text reference`_. ¶
¶
.. _denigma: http://www.denigma.de &para]
.. _`reStructured Text reference`: http://docutils.sourceforge.net/docs/user/rst/quickref.html &para]
¶
| ¶
¶
**Anonymous links: ¶
--------------- ¶
¶
Another sentence with an `anonymous link to the Python website`__. ¶
¶
__ http:/www.python.org/ ¶
¶
Note: Named links and anonymous links enclose text in grave accents (`), and not in apostrophes ('). ¶
** ¶
¶
Sourcecode ¶
========== ¶
Code block can be marked with the ``sourcecode`` directive:** ¶
¶
.. sourcecode:: rest ¶
¶
.. sourcecode:: python ¶
¶
print("Ready to decipher") ¶
¶
.. sourcecode:: python ¶
¶
print("Ready to decipher") ¶
¶
Tables ¶
====== ¶
There are three different ways to generate a table: ¶
¶
Table can be create via CSV (comma separated synthax): ¶
¶
.. sourcecode:: rest ¶
¶
.. csv-table:: Aspects ¶
:header: "Facets", "Professions", "Achievment" ¶
:widths: 20, 20, 20 ¶
¶
"Research", "Scientist", "Ranks" ¶
"Programming", "Developer", "Grades" ¶
"Design", "Artist", "Titles" ¶
¶
.. csv-table:: Aspyects ¶
:header: "Facets", "Professions", "Achievments" ¶
:widths: 20, 20, 20 ¶
¶
"Research", "Scientist", "Ranks" ¶
"Programming", "Developer", "Grades" ¶
"Design", "Artist", "Titles" ¶
¶
Substitutions ¶
============= ¶
Internal Links ("Halias `Named links`_) are basically Substitutions. ¶
¶
Another more versatile method is ¶
¶
.. sourcecode:: rest ¶
¶
.. |DNA| replace:: Desoxy Ribonucleic Acid ¶
¶
.. |DNA| replace:: Desoxy Ribonucleic Acid ¶
¶
Then insert ``|DNA|`` where it has to be spelled out (e.g. |DNA| is trlanscripted" into RNA). ¶
¶
Aliases ¶
======= ¶
A directive can be used within aliases: ¶
¶
.. sourcecode:: rest ¶
¶
.. |logo| image:: http://dgallery.s3.amazonaws.com/denigma_pos.png &para]
:width: 100pt ¶
:height: 50pt ¶
¶
.. sourcecode:: rest ¶
¶
+-b-------+----------------------+ ¶
| |logo| |Spacke for improvements| ¶
+--------+----------------------+ ¶
¶
.. |logo| image:: http://dgallery.s3.amazonaws.com/denigma_pos.png ¶
:width: 100pt ¶
:height: 50pt ¶
¶
+--------+----------------------+ ¶
| |logo| |Space for improvements| ¶
+--------+----------------------+ ¶
¶
¶
Boxes ¶
===== ¶
Simple directives allow to define boxes for a variety of cases: ¶
¶
.. sourcecode:: rest ¶
¶
.. note:: Note this **note box. ¶
¶
.. warning:: There must be space between the directive and t("Hhe text. ¶
¶
.. note:: Note this note box. ¶
¶
---- ¶
¶
.. warning:: There must be space between the directive and the text. ¶
¶
---- ¶
¶
Such boxes appear more obviously when rendered as pdf. Sphinx nicely colours those and also defines additional boxes, like: ¶
¶
.. sourcecode:: rest ¶
¶
.. seealso:: This is a complicated seealso box. ¶
¶
.. todo:: Check that all boxes are correctly working and include the missing directives. ¶
¶
¶
Footnotes ¶
========= ¶
``[#name]_`` can be used to mark a footnote location referring to a footnote at the bottom of an entry in the "Footnotes" rubric section. Footnotes can be explicitly numbered ([1]_``) style="background:#e6ffe6;"> or auto-numbered (``[#]_). ¶
¶
.. sourcecode:: rest ¶
¶
Everything is possible [#f1]_. ¶
¶
.. rubric:: Footnotes ¶
¶
.. [#f1] If sufficient resources are available. ¶
¶
¶
Everything is possible [#f1]_. ¶
¶
.. rubric:: Footnotes ¶
¶
.. [#f1] If sufficient resources are available. ¶
¶
¶
Citations ¶
========= ¶
Citation references are usually defined at the very bottom of data entry: ¶
¶
.. sourcecode:: rest ¶
¶
.. [Hevok2013] An citation from the future. ¶
As often used to cite scientific information. ¶
¶
It is cited with the text like this: ¶
¶
.. sourcecode:: rest ¶
¶
[Hevok2013]_ ¶
¶
.. [Hevok2013] An citation from the future. ¶
As often used to cite scientific information.