Created on Oct. 25, 2012, 2:46 p.m. by Hevok & updated by Hevok on May 2, 2013, 5:10 p.m.
| 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. |
|---|
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:
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):
Just follow to simple rules:
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 are very simple an intuitive implemented and they come in different flavours.
- A bullet list item
- Second item
- A sub item
- Third item
1) An enumerated list item
2) Second item
a) Sub item
i) Sub-sub item
3) Third item which uses
two lines (note indention).
#) Another enumerated list item
#) Second item
A field list allows to simply create some fields with following text being intended:
: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. |
An alternative is list definition:
Research
About understanding nature.
Programming
Enables to automate information technologies.
Design
Requires creativity and innovation.
.. image:: http://dgallery.s3.amazonaws.com/rst.png
.. image:: http://dgallery.s3.amazonaws.com/denigma_pos.png
:width: 200px
:height: 100px
:align: center
:alt: Alternative text
.. 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
Figures are like images but with a caption
and anything else can be added to it
import image
To create a link to a website, the synthax is the following:
``_
This appears as http://www.denigma.de. An optional label can be defined too:
```Digital enigma `_``
That renders into Digital enigma
Every title/header is a hyperlink. A link to a section is just its name with in quotes followed by underscore:
`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:
.. _rst:
It can be referred to it in two ways:
simple:
rst_
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.
A sentence with links to denigma_ and the `reStructured Text reference`_.
.. _denigma: http://www.denigma.de
.. _`reStructured Text reference`: http://docutils.sourceforge.net/docs/user/rst/quickref.html
A sentence with links to denigma and the reStructured Text reference.
Another sentence with an anonymous link to the Python website.
Note: Named links and anonymous links enclose text in grave accents (`), and not in apostrophes (').
Code block can be marked with the sourcecode directive:
.. sourcecode:: python
print("Ready to decipher")
print("Ready to decipher")
There are three different ways to generate a table:
Table can be create via CSV (comma separated synthax):
.. csv-table:: Aspects
:header: "Facets", "Professions", "Achievment"
:widths: 20, 20, 20
"Research", "Scientist", "Ranks"
"Programming", "Developer", "Grades"
"Design", "Artist", "Titles"
| Facets | Professions | Achievments |
|---|---|---|
| Research | Scientist | Ranks |
| Programming | Developer | Grades |
| Design | Artist | Titles |
Internal Links (alias Named links) are basically Substitutions.
Another more versatile method is
.. |DNA| replace:: Desoxy Ribonucleic Acid
Then insert |DNA| where it has to be spelled out (e.g. Desoxy Ribonucleic Acid is transcripted into RNA).
A directive can be used within aliases:
.. |logo| image:: http://dgallery.s3.amazonaws.com/denigma_pos.png
:width: 100pt
:height: 50pt
+--------+----------------------+
| |logo| |Space for improvements|
+--------+----------------------+
|
Space for improvements |
Simple directives allow to define boxes for a variety of cases:
.. 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:
.. seealso:: This is a complicated **seealso** box.
.. todo:: Check that all boxes are correctly working and include the missing directives.
Everything is possible [#f1]_.
.. rubric:: Footnotes
.. [#f1] If sufficient resources are available.
Everything is possible [1].
| [1] | If sufficient resources are available. |
Citation references are usually defined at the very bottom of data entry:
.. [Hevok2013] An citation from the future.
As often used to cite scientific information.
It is cited with the text like this:
[Hevok2013]_
| [Hevok2013] | An citation from the future. As often used to cite scientific information. |
Comment on This Data Unit