created on Oct. 25, 2012, 2:46 p.m. by Hevok & updated on Nov. 23, 2012, 6:35 p.m. by Hevok
.. _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.
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.
.. sourcecode:: rest
- A bullet list item
- Second item
- A sub item
- Third 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).
.. sourcecode:: rest
#) Another enumerated list item
#) Second item
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.
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.
.. sourcecode:: rest
.. image:: http://dgallery.s3.amazonaws.com/rst.png
.. image:: http://dgallery.s3.amazonaws.com/rst.png
.. sourcecode:: rest
.. image:: http://dgallery.s3.amazonaws.com/denigma_pos.png :width: 200px :height: 100px :align: center :alt: Alternative text
.. image:: http://dgallery.s3.amazonaws.com/denigma_pos.png :width: 200px :height: 100px :align: center :alt: Alternative text
.. 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 :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 are marked with simple two dots:
.. sourcecode:: rest
.. comments
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)
To create a link to a website, the synthax is the following:
.. sourcecode:: rest
`<http://www.denigma.de>]`_
This appears as <http://www.denigma.de>]_. An optional label can be defined too:
.. sourcecode:: rest
```Digital enigma <http://www.denigma.de>]`_``
That renders into Digital enigma <http://www.denigma.de>]_
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`_
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:
.. sourcecode:: rest
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.
.. sourcecode:: rest
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_.
.. denigma: http://www.denigma.de
.. reStructured Text reference: http://docutils.sourceforge.net/docs/user/rst/quickref.html
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 (').
Code block can be marked with the sourcecode directive:
.. sourcecode:: rest
.. sourcecode:: python
print("Ready to decipher")
.. sourcecode:: python
print("Ready to decipher")
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"
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).
A directive can be used within aliases:
.. sourcecode:: rest
.. |logo| image:: http://dgallery.s3.amazonaws.com/denigma_pos.png
:width: 100pt
:height: 50pt
.. sourcecode:: rest
+--------+----------------------+
| |logo| |Space for improvements|
+--------+----------------------+
.. |logo| image:: http://dgallery.s3.amazonaws.com/denigma_pos.png :width: 100pt :height: 50pt
+--------+----------------------+ | |logo| |Space for improvements| +--------+----------------------+
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.
[#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.
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.
Comment on This Data Unit