reStructured Text

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.

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:

Embed images you have uploaded

Include notes, warnings, and other Admonitions like:

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

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:

2.6   Citations

Here is a citation reference: [CIT2002].

2.7   Lists

Items in bullet lists are prepended with *, +, -

2.8   Tables

There are three ways of creating tables in reST:

====================  ==========  ==========
Header row, column 1  Header 2    Header 3
====================  ==========  ==========
body row 1, column 1  column 2    column 3
body row 2            Cells may span columns
====================  ======================

+------------------------+------------+----------+
| Header row, column 1   | Header 2   | Header 3 |
+========================+============+==========+
| body row 1, column 1   | column 2   | column 3 |
+------------------------+------------+----------+
| body row 2             | Cells may span        |
+------------------------+-----------------------+

.. 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!

.. 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!"

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:

Example:

1.. image:: 39
2  :alt: Volume Rendered Earth
3  :width: 256

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

.. warning:: Be Warned!!!

Admonitions are blocks

3.5   Other

It is possible to embed YouTube videos inside articles using the

.. youtube:: id directive, where id can either be the YouTube video ID or the URL to the video.

4.1   List Types

4.2   Interpreted Text Roles

See <http://docutils.sf.net/docs/ref/rst/roles.html> for more information on reST specific interpreted text roles

4.3   Directives Reference

See <http://docutils.sf.net/docs/ref/rst/directives.html> for full info.

4.4   Explicit Markup