reStructured Text
1 About
1.1 What is reST?
reStructured Text is a plaintext markup system for writing documents. You can read more about it at the official reST information page, from where we have taken most of the information and examples for this help page.
The reST supported by Siafoo has been customized in a number of ways in order to make it fit with the website and also provide capabilities that do not exist in the standard implementation.
1.2 What can it do?
If you are the hands-on kind, you might like to try the Siafoo reST demo before continuing with the documentation.
Like other text formatting systems, reST is capable of making things bold (*bold*), or italic (**italic**). It is also capable of creating links to other documents (see Links).
Using reST you can:
Format your document in sections, like the sections in this help page, and you can place links to individual sections, for example `Sections`_ will create a link to the Sections section.
Note
If using sections, make sure to create a Table of Contents.
You can include Siafoo snippets (.. snippet:: 1)
1print 'Hello World!'
or inline code blocks
1a = [i for i in range(100) if i % 2 == 0]
Include simple charts in your documents (See Charts) like this one (based on absolute fiction):
Or flow Graphs like this:
Embed mathematical formulas and equations using LaTeX Style Math like:
Reference articles, snippets (Python Hello World) or other Siafoo objects using simple interpreted text roles, like :snippet:`1`.
Reference books OpenGL® Programming Guide: The Official Guide to Learning OpenGL®, Version 2
and create citations (see Citations):
OpenGL Architecture Review Board, OpenGL® Programming Guide: The Official Guide to Learning OpenGL®, Version 2, Addison-Wesley Professional
Create lists of items by prepending a *, +, or - (see Lists) to the beginning of the string.
Create tables (see Tables) like:
| Treat | Quantity | Description |
|---|---|---|
| Albatross | 2.99 | On a stick! |
| Crunchy Frog | 1.49 | If we took the bones out, it wouldn't be crunchy, now would it? |
| Gannet Ripple | 1.99 | On a stick! |
Embed images you have uploaded
Include notes, warnings, and other Admonitions like:
Warning
Do not paste "sudo rm -rf /" into your terminal, unless you are using DOS,
2 Basics
2.1 Paragraphs
Paragraphs are pieces of text separated by one or more blank lines, they must have the same indentation level. Indenting a paragraph will result in an indented quote paragraph.
Example
This is a paragraph. It's quite short.
This paragraph will result in an indented block of text, typically used for quoting other text.
This is another one.
2.2 Styles
For italics surround the text with asterisk, like *italics*.
For bold surround the text with double asterisk, like **bold**
For inline literals, surround the text with double backticks (`), like ``literal``
2.3 Links
In general pasting a simple link http://docutils.sourceforge.net/rst.html will make it hot. To add a label you can mark up the string like: `reST <http://docutils.sourceforge.net/rst.html>`_ which will result in the link: reST
Warning
The name of the link, in this case reST must be unique in the document.
When you have a target name, whether created explicitly using the link syntax above or implicitly by the sections you can reference it using a syntax like `Some target name`_.
2.4 Sections
To break up a document into sections, you simply underline or underline and overline the section title using any one of the following characters = - ` : ' " ~ ^ _ * + # < >. Sections decorated with the same character are treated as having the same section level. A section underlined with one character is treated as a different section than a section that has been overlined and underlined with the same character
Example:
Chapter 1 Title =============== Section 1.1 Title ----------------- Subsection 1.1.1 Title ~~~~~~~~~~~~~~~~~~~~~~ Section 1.2 Title ----------------- Chapter 2 Title ===============
The reST parser automatically creates targets for sections, so you can reference them at any point using `Chapter 1 Title`_
Placing the sectnum directive above the beginning of sections will autonumber the sections bellow it.
2.5 Table of Contents
For sectioned documents it is recomennded that you place the following reST directives at the top of your document, in order to create a hyperlinked table of contents like the one on this help page:
.. sidebar:: Contents .. contents:: .. sectnum::
The contents directive can be placed at the beginning of the document or at the beginning of a section. When placed at the beginning of a section, and the argument :local: is provided the table of contents will only provide sub links for the subsections of the current section.
The contents directive supports the following arguments:
| Arguments | Examples |
|---|---|
| depth | The number of section levels that are collected in the table of contents. The default is unlimited depth. |
| local | Generate a local table of contents |
| backlinks | Generate links from section headers back to the table of contents entries, the table of contents itself, or generate no backlinks. |
2.6 Citations
Here is a citation reference: [CIT2002].
| [CIT2002] | This is the citation. It's just like a footnote, except the label is textual. |
2.7 Lists
Items in bullet lists are prepended with *, +, -
2.8 Tables
There are three ways of creating tables in reST:
2.8.1 Basic
The simple way:
==================== ========== ========== Header row, column 1 Header 2 Header 3 ==================== ========== ========== body row 1, column 1 column 2 column 3 body row 2 Cells may span columns ==================== ======================
And the more explicit way, similar to ASCII art,
+------------------------+------------+----------+ | Header row, column 1 | Header 2 | Header 3 | +========================+============+==========+ | body row 1, column 1 | column 2 | column 3 | +------------------------+------------+----------+ | body row 2 | Cells may span | +------------------------+-----------------------+
both of these definitions will result in:
Header row, column 1 Header 2 Header 3 body row 1, column 1 column 2 column 3 body row 2 Cells may span
2.8.2 List Table
.. list-table:: Frozen Delights!
:widths: 15 10 30
:header-rows: 1
* - Treat
- Quantity
- Description
* - Albatross
- 2.99
- On a stick!
* - Crunchy Frog
- 1.49
- If we took the bones out, it wouldn't be
crunchy, now would it?
* - Gannet Ripple
- 1.99
- On a stick!
| Treat | Quantity | Description |
|---|---|---|
| Albatross | 2.99 | On a stick! |
| Crunchy Frog | 1.49 | If we took the bones out, it wouldn't be crunchy, now would it? |
| Gannet Ripple | 1.99 | On a stick! |
2.8.3 CSV Table
.. csv-table:: Frozen Delights! :header: "Treat", "Quantity", "Description" :widths: 15, 10, 30 "Albatross", 2.99, "On a stick!" "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be crunchy, now would it?" "Gannet Ripple", 1.99, "On a stick!"
Will produce the same table as the one for List Table
2.9 Directives
For achieving more complicated tasks, such as embedding images, reST supports special commands call directives. The syntax for a directive is .. directive_name:: where directive_name is the name of the directive. Some directives allow (and sometimes expect) arguments in the form :argument_name: some_data that control the directive.
See the Directives Reference bellow for a list of common directives.
reST already comes with a rich set of directives for inserting images, warning boxes, and things of that nature. We have expanded this set with custom Siafoo directives for embedding snippets, soure code, charts and videos into articles and other reST enabled edit boxes.
2.10 Images
Siafoo supports the full syntax and options for the reST image directive, with the exception that instead of an URL one must put the id of the target image.
There two ways to upload images: using the image management page of your user profile or by directly uploading images through the article/snippet create/edit form. When using the create/edit form the software will place the correct image directive at the bottom of the document.
If the article, snippet, etc. is owned by a Siafoo Group you can upload images to the group and include them in the article, snippet, etc.
Images can be shared between articles but you must be the owner of the image, that is you must have uploaded the image at one point, before you can use it inside an Article. This behavior is something of a security feature, preventing people from embedding your image in their articles and subsequently preventing you from deleting the image. Naturally you can't delete an image if it is used inside an article, as this will create inconsistent content.
To include an image, use the .. image::ID directive, where id is the numerical id of the image.
The following arguments are supported for images:
| Arguments | Description |
|---|---|
| alt : text | A short description of the image (the "alt" attribute in the HTML <img> tag) |
| height : integer | Height of image in pixels |
| width : integer | Width of image in pixels |
| align: | The alignment of the image, (the "align" attribute of the HTML <img> tag). The values "top", "middle", and "bottom" control an image's vertical alignment (relative to the text baseline); The values "left", "center", and "right" control an image's horizontal alignment, allowing the image to float and have the text flow around it. |
| target: | Makes the image into a hyperlink reference ("clickable"). The option argument may be a URI (relative or absolute), or a reference name with underscore suffix (e.g. name_). |
Example:
1.. image:: 39
2 :alt: Volume Rendered Earth
3 :width: 256
3 Siafoo Specific Extensions
3.1 Embedding Snippets and Code
There are two ways to embed code inside an article.
Using the .. snippet:: id directive, where id is the snippet id. If an embedded snippet is updated it will also be updated inside the article, so all changes are reflected.
For example: .. snippet:: 1 will result in the following:
1print 'Hello World!'
The second way to embed code is by using the .. code:: language_name directive where the language_name is the name of the
desired language. The code must be one indent level below the code directive and separated from the directive with a blank line. Like
1.. code:: Python
2
3 print 'hello world'
For a list of supported languages and their names, see Supported Languages
3.2 Referencing Snippets, Articles and other Objects
One can put a link to an article, snippet, library, group or algorithm directly inside a reST block by using the intepreted text role :snippet:`1`
3.3 Charts
One can embed charts inside Siafoo articles and other reST enabled fields by using any of the supported chart directives. The charts are rendered by a Google Chart API compatible chart server, on the fly and displayed inside the article as an image.
Currently supported chart formats are bar graph, line graph and pie charts. See the Charts help page for more information
3.4 Admonitions
.. note:: I am a note
Note
I am a note
.. warning:: Be Warned!!!
Warning
Be Warned!!!
Admonitions are blocks
4 Reference
Below you will find a list of the supported directives and interpreted text roles by the Siafoo reST parser. If a directive or text role is not listed in the tables below, it is most likely removed from the parser. We have removed several directives, such as embedding raw html inside the reST blocks, directives because they pose a security or privacy thread to our users and we have removed other directives, such as meta tags, because they don't make sense in the context of Siafoo Articles.
4.1 List Types
| List Type | Examples | ||
|---|---|---|---|
| Bullet list |
|
||
| Enumerated list |
|
||
| Definition list |
|
||
| Field list |
|
||
| Option list |
|
4.2 Interpreted Text Roles
| Role Name | Description |
|---|---|
| algorithm | Reference to a Siafoo algorithm by id |
| article | Reference to a Siafoo article by id |
| group | Reference to a Siafoo group by id |
| help | Reference to a Siafoo help page by id or name |
| library | Reference to a Siafoo library by id |
| snippet | Reference to a Siafoo snippet by id |
| emphasis | Equivalent to emphasis |
| literal | Equivalent to literal but processes backslash escapes |
| PEP | Reference to a numbered Python Enhancement Proposal |
| RFC | Reference to a numbered Internet Request For Comments |
| strong | Equivalent to strong |
| sub | Subscript |
| sup | Superscript |
| title | Title reference (book, etc.); standard default role |
See <http://docutils.sf.net/docs/ref/rst/roles.html> for more information on reST specific interpreted text roles
4.3 Directives Reference
| Directive Name | Description (Docutils version added to, in [brackets]) |
|---|---|
| attention | Specific admonition; also "caution", "danger", "error", "hint", "important", "note", "tip", "warning" |
| admonition | Generic titled admonition: .. admonition:: By The Way |
| image | .. image:: image_id; many options possible |
| figure | Like "image", but with optional caption and legend |
| topic | .. topic:: Title; like a mini section |
| sidebar | .. sidebar:: Title; like a mini parallel document |
| parsed-literal | A literal block with parsed inline markup |
| rubric | .. rubric:: Informal Heading |
| epigraph | Block quote with class="epigraph" |
| highlights | Block quote with class="highlights" |
| pull-quote | Block quote with class="pull-quote" |
| compound | Compound paragraphs |
| container | Generic block-level container element |
| table | Create a titled table |
| list-table | Create a table from a uniform two-level bullet list |
| csv-table | Create a table from CSV data (requires Python 2.3+) |
| contents | Generate a table of contents |
| sectnum | Automatically number sections, subsections, etc. |
| target-notes | Create an explicit footnote for each external target |
| replace | Replacement text for substitution definitions |
| unicode | Unicode character code conversion for substitution defs |
See <http://docutils.sf.net/docs/ref/rst/directives.html> for full info.
4.4 Explicit Markup
| Explicit Markup | Examples |
|---|---|
| Footnote |
|
| Citation | .. [CIT2002] A citation. |
| Hyperlink Target | .. _reStructuredText: http://docutils.sf.net/rst.html .. _indirect target: reStructuredText_ .. _internal target: |
| Anonymous Target | __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html |
| Directive ("::") | .. image:: 1337 |
| Substitution Def | .. |substitution| replace:: like an inline directive |
| Comment | .. is anything else |
| Empty Comment | (".." on a line by itself, with blank lines before & after, used to separate indentation contexts) |