.. _rst: ¶
¶
================ ¶
reStructuredText ¶
================ ¶
.. _rst: ¶
.. 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 ¶
---------- ¶
¶
The title is unique and is usually defined at the very beginning (that's why it is omitted here): ¶
¶
Header ¶
====== ¶
¶
Subsection ¶
---------- ¶
¶
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 ¶
: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 &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 ¶
¶
.. 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 &para]
¶
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:: Aspects ¶
:header: "Facets", "Professions", "Achievments" ¶
:widths: 20, 20, 20 ¶
¶
"Research", "Scientist", "Ranks" ¶
"Programming", "Developer", "Grades" ¶
"Design", "Artist", "Titles" ¶
¶
Substitutions ¶
============= ¶
Internal Links (alias `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 transcripted 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 ¶
¶
+--------+----------------------+ ¶
| |logo| |Space for improvements| ¶
+--------+----------------------+ ¶
¶
.. |logo| image:: http://dgallery.s3.amazonaws.com/denigma_pos.png &para]
: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 the 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]_) 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.