reStructured Text 0

1.1   What is reST?

reStructured Text is a customizable plaintext markup system for writing documents. For general information on reST, visit the official reST home page.

This tutorial will get you started writing reST syntax, including some directives we've created just for Siafoo.

If you are a hands-on sort of person, you might like to follow along using the Siafoo reST demo.

Already created some content, but it's in HTML format? You might want to use our HTML to reST translator.

1.2   What can it do?

What can reST do? The short answer is a lot. This whole help page is written in reST!

reST is of course capable of styling text bold, italic, and monospaced. Like every other text formatting system, it can create links, lists, and tables. You can organize your document into sections, which automatically get anchors. As you can see you can make a table of contents too. But that's not the cool part, that is just 'how to let users write HTML securely' (ok the TOC is a little cool).

What really makes Siafoo's reST powerful is what else you can do (and how integrated with the rest of the site it is).

You can reference Siafoo objects like snippets: :snippet:`9` creates Brainfuck Hello World. The title is fetched and updated automatically. You can also reference books by ISBN: :book:`978-0201889543` creates C++ Programming Language, The. The book's data is fetched from Amazon automatically.

You can easily include Siafoo snippets. When the snippet is updated, so is the article. (The syntax is just ".. snippet:: 1"):

1print 'Hello World!'

Only have a bit of code? You can embed it straight into the article:

1a = [i for i in range(100) if i % 2 == 0]

Easily create and render a chart, like this completely fictitious one:

Use simple syntax to draw a flow graph like this one:

Write mathematical formulas and equations:

Embed an image you've uploaded...

xkcd, while awesome, is in no way associated with Siafoo. And images can have captions!

... or a YouTube video:

Ready to sign up for an account yet? :)

2.1   Paragraphs

Paragraphs are blocks of text, separated by blank lines. If you don't separate a blank line, text will run together. This is a common frustration of first time reST programmers, especially when cutting and pasting text from a README or something similar.

You can also indent paragraphs. Typically this is used for quoting.

It may appear possible to not separate the indented paragraph from the one above it,

but in this case you are actually creating a definition list. Use at your own risk : )

Here's an example:

This is a short paragraph.

    This is an indented paragraph.

This is another short paragraph.
Whoops, I've forgotten to put a blank line above this one.

This text creates:

This is a short paragraph.

This is an indented paragraph.

This is another short paragraph. Whoops, I've forgotten to put a blank line above this one.

2.2   Sections

To break up a document into sections, you underline (or underline and overline) the entire section title using one of the characters:

= - ` : ' " ~ ^ _ * + # < >

Sections decorated with the same character belong to the same 'section level'. However, a section underlined only counts as a different section than one overlined and underlined. Sections with the same 'section level' get the same size headline. For example, this page's section titles look something like:

Chapter 1 Title
===============

Section 1.1 Title
-----------------

Subsection 1.1.1 Title
**********************

Section 1.2 Title
-----------------

Chapter 2 Title
===============

Sorry, no live example for this one, but you can look at how this page is laid out to get an idea of how section titles work.

Note that a target is created for each section by default; the above "Chapter 1 Title" could be linked to with `Chapter 1 Title`_

Chapter 1 Title
===============

Section 1.1 Title
-----------------

Chapter 2 Title
===============

Section 1.2 Title
*****************

.. sidebar:: Contents

    .. contents::

.. sectnum::

2.3   Styles

Styles are easy:

For Italics, surround the text with asterisks. like *Italics*

For Bold, surround the text with double asterisks, like **Bold**

For Literals, surround the text with double backticks, like ``Literals``. Literals are monospace and the text inside is not evaluated further. Most of the inline reST on this page is created this way.

Here is an example::

    Look, ``styles`` don't get **processed**

2.4   Links

You can create a link by just pasting it in. Entering http://docutils.sourceforge.net/rst.html creates http://docutils.sourceforge.net/rst.html.

To add a label, you must mark up the string: `label <link>`_ (don't forget the space in between or the underscore). For example, entering `reST <http://docutils.sourceforge.net/rst.html>`_ creates the link reST.

You only have to do this once per link; you can reference the same link again by just using the label: now `reST`_ creates reST.

.. [1] This is footnote 1.
.. [LABEL] This is a citation or labeled footnote.
.. [#] This is our auto numbered footnote.

2.5   Lists

Lists must have a blank line below and above them.

To make a bulleted or 'unordered' list, prepend each item with *, +, - and a space. You must use the same sort of bullet for each item however. To make a numbered or 'ordered' list, prepend each item with a number or a '#' (for autonumbering) and a space. To create a definition list, indent text without leaving a blank line. You can nest lists by further indenting the nested list. For example:

* This is a bulleted list item
* So is this

    1. This is a nested numbered list
    #. Here's another item

And here's a definition title
    And the definition content

This text creates:

• This is a bulleted list item

• So is this

• So is this

  1. This is a nested numbered list
  2. Here's another item

And here's a definition title

And the definition content

2.6   Interpreted Text Roles and Directives

Obviously there aren't enough characters to have a different way to mark up each thing you might want to do in reST. To work around this problem, reST has interpreted text roles and directives. These allow more complicated tasks.

Interpreted text roles are for advanced inline markup. They look like :role:`argument`. Think of it as passing an argument to a function.

Directives are similar, but create blocks. They accept multiple arguments and content. They look like this:

.. directive:: main_value
    :arg1: value1
    :arg2: value2

    content goes here

Not all directives take a main value, arguments, and content. They may take none, some, or all of these. Arguments are almost always optional.

Directives are very powerful, but it is easy to mess up the syntax: the '..' is separated from the directive name by a space, the '::' is NOT, and the main value is separated from the '::' by a space. Arguments and content are indented (at the same level). A blank line separates the directive, main value, and arguments from the content, even when there are no sub-arguments. Sometimes when you forget or add a character, the whole thing just disappears with no error! Don't worry though, it is easy to get the hang of it.

Many of the methods from here on out use either roles or directives.

2.7   Admonitions

Admonitions are notes, warnings, or other sorts of extra information set out from the rest of the text. To create one, you use a directive with the name of that admonition ('attention', 'caution', 'danger', 'error', 'hint', 'important', 'note', 'tip', 'warning'). You pass it the text you want used as the 'value' of the directive and/or as the directive's content. For example, a 'warning' admonition would be specified like:

.. warning:: Don't do that!

    I mean it!

It would then look something like this:

Warning

Don't do that!

I mean it!

The others look similar, but with slightly different styles.

You can also specify your own title with the admonition::title tag. In this case the text must be passed as directive content:

.. admonition:: Look a custom title!

    Here is some content.

When rendered, this one looks like:

Look a custom title!

Here is some content.

2.8   Tables

There are three or four ways of creating tables in reST, depending on how you count them. I think they are fairly self explanatory.

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

3.1   Books

You can reference a book by ISBN; Siafoo uses Amazon's API to look up the title of the book and to provide a link to Amazon. Why use the ISBN and not just the title? Two reasons:

• Anyone reading will know exactly which version of the book you are talking about. The worst is to buy a book and realize that what you wanted was only in the next/previous edition.
• We get a small commission for each book bought through one of these links, so you are supporting Siafoo. :)

You can get an inline link by using the role :book:`ISBN`. For example :book:`978-0201889543 ` will create C++ Programming Language, The.

For more information or to get a proper 'reference' format, you can use the directive:

.. book:: 978-0201889543

This creates:

Bjarne Stroustrup, C++ Programming Language, The, Addison-Wesley Professional

3.2   Snippets, Articles and other Siafoo Objects

You can put a link to an algorithm, article, group, library, or snippet by using an interpreted text role like :item_type:`id`. If the title is changed, it will be automagically updated in your page. For example:

Some of our post popular items are :algorithm:`5` and :article:`52`?
One of the first things on Siafoo was :library:`1`.
You should consider joining :group:`3`.  I really like the snippet :snippet:`9`.

This creates:

Some of our post popular items are BogoSort and Python Tips, Tricks, and Hacks? One of the first things on Siafoo was Language Demos. You should consider joining the Siafoo Users Group. I really like the snippet Brainfuck Hello World.

You can also reference help pages if for some reason you'd like to. Use the :help: role with the help page name (the 'name' is what the URL displays, as opposed to the full title). So :help:`reST` will create a link to the page you are at right now: reStructured Text.

4.1   Images

You can upload an image using your image management page, or by directly using the 'Add Image' fields in any create or edit form. When using the create or edit form, upon uploading an image the correct directive will be placed at the bottom of the reST content.

If the item you are creating or editing is owned by a Siafoo Group, you can upload images to the group as well.

You can only add images that are owned by you or the same group as the item you are creating or editing. However, you can move images that others have added within the reST for that item.

Naturally, you can't delete an image if it is used inside an article, as this will make things inconsistent.

To include an image, use the .. image::id directive, where id is the numerical id of the image.

For advanced use, the following arguments are supported. The image directive does not take any 'content'.

For example:

.. image:: 39
   :alt: Volume Rendered Earth
   :width: 256

This code creates:

.. figure:: 39
   :alt: Volume Rendered Earth
   :width: 256
   :figwidth: 300

   This is the Earth.  If I write a long caption it should be contained because of the figwidth option.

4.2   Videos

You can embed YouTube videos inside reST using the .. youtube:: id directive, where id can either be the YouTube video ID or the URL to the video. For example:

.. youtube:: http://www.youtube.com/watch?v=z2BgjH_CtIA

This results in:

4.3   Embedding Snippets and Code

There are two ways to embed code inside an article.

To embed an entire snippet, use the .. snippet:: id directive, where id is the snippet id. If an embedded snippet is updated it will be automagically updated inside the reST. This is the best thing to do for larger blocks of code (heh unlike this example), or code you'd like to set a separate license for. You get a link to the snippet too. For example:

.. snippet:: 1

will result in the following:

Python Hello World

# 's

1print 'Hello World!'

This snippet is licensed under the Public Domain license

You can also embed arbitrary code using the .. code:: language_name directive where the language_name is the short name of the desired language. You can find a list of supported languages and their short names at Supported Languages.

The actual code should be the 'content' of the directive: indented and separated by a blank space. For example:

.. code:: Python

    print 'This is another Hello World'

This code creates:

# 's

1print 'This is an inline code block! Yay!'

4.4   Charts

You can create pie, bar, and line charts. For example:

.. piechart::
  :title: Visitors with Firefox
  :data: 36.30, 55.40, 8.3
  :colors: f5f700, 0087f7, f79b00
  :labels: Firefox 3 (36.0%), Firefox 2.0.0.14 (55.40%), Other Firefox 2 (8.3%)
  :3d:

This code creates:

We have a whole page about creating charts: Charts

4.5   Flow Graphs

Siafoo lets you create flow graphs in the Graph::Easy, Graphviz, and VCG formats. Our rendering engine is quite powerful; this little bit of code:

.. graph::

  node.hdr { color: red; }
  node.src { fill: lightgreen; }
  node.stage { fill: lightblue; }

  (Libraries: [Library 1]{ shape: diamond;},
              [Library 2]{ shape: diamond;},
              [Library 3]{ shape: diamond;})

  [Header 1]{class: hdr;},
  [Header 2]{class: hdr;},
  [Header N]{class: hdr;}-> [Preprocessor]{shape:circle; class:stage;} -> [Intermediate 2],
                                                                          [Intermediate 1] ->[Compiler]
  [Source 1]{class: src;}, [Source 2]{class: src;}-> [Preprocessor]

  [ Compiler ]{shape:circle; class:stage;} -> [ Object 2], [ Object 1] -> [ Linker ]

  [Library 1], [Library 2], [Library 3] -> [Linker]{shape:circle; class:stage;}
  [Linker] -> [Binary2]

Creates a fairly complex graph:

For information on flow graphs, see Flow Graphs.

4.6   LaTeX Style Math

Finally, you can embed LaTeX-style math expressions using an inline text role or a directive. You can use the inline text role: :math:`E=mc^2` creates . Or you can use the directive for larger equations:

.. math:: align

    \nabla \cdot E &= \frac{1}{\epsilon_0} \rho\\
    \nabla \cdot B &= 0\\
    \nabla \times E &= -\frac{\partial B}{\partial t}\\
    \nabla \times B &= \mu_0 J + \mu_0 \epsilon_0 \frac{\partial E}{\partial t}

This code creates:

We have a whole page about this too: LaTeX Style Math

5.1   Explicit Markup

5.2   List Types

5.3   Interpreted Text Roles

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

5.4   Directives Reference

See http://docutils.sf.net/docs/ref/rst/directives.html for more information on directives.

7.1   Siafoo reST Syntax

Charts

Flow Graphs

LaTeX Style Math

Citations

7.2   General reStructured Text Info

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

http://docutils.sourceforge.net/docs/user/rst/quickstart.html

http://docutils.sourceforge.net/docs/ref/rst/directives.html