A beginner’s guide to reStructuredText

This is a quick reference for reStructuredText (reST). It covers some of the most commonly used features. The following resources are much more comprehensive and come straight from the authoritive reST sources:

• Sphinx - reST Primer
• Docutils - A reST Primer
• Docutils - the complete reST markup specification

If you are using Vim, you may want to look at .vimrc configurgation to make writing documentation easier.

Sections

When creating a new section, make sure that the underline (and overline if necessary) have the same number of characters as the section title.

==============
Section Header
==============

Section
=======

Subsection
----------

Subsubsection
^^^^^^^^^^^^^

Paragraphs are generated by one or more blank lines. All lines of the
paragraph must have the same level of indentation.

Lists

* This is an unorderded (bulleted) list.
* It has two items, the second item spans
  multiple lines and has to be appropriately indented.

#. This is a numbered list of two items.
#. The numbers are automatically generated.

Styling

*emphasis (italics)*
**emphasis (boldface)**
``code``

Code blocks

Code blocks are formed the following way:

::

    This text will appear in a code block.
    This inner text must be indented and seperated by a newline.

Internal hyperlinks

To make an internal link, first define a label above the section/header you want to link to.

.. _widget-making:

How to make widgets
-------------------

Then, link to it using :ref:`my-label-name:

For more information on widget building, check out :ref:`widget-making`.

External hyperlinks

External links are formed like this: `this text is a link <http://www.example.com>`_

When linking to external sources, seperate the link from the target definition. This means the the link title and the address are seperate, which makes the documentation more readable from the text editor. Put all the target definitions at the bottom of the section or file. The following is an example.

Example: If you want to search for things, you should go to Google. Google is really fast!

If you want to search for things, you should go to `Google`_. Google is
really fast!

.. _Google: http://www.google.com

Anonymous links can also be used with the following syntax. In some cases, this style is cleaner to use. The targets of each label are assigned to the anonymous links sequentially.

For my searching needs, I use `Google`__.
Whenever I am looking for the weather I go to `Yahoo!`__.
And if I am want the latest movie news, I check out `Rotten Tomatoes`__.

__ http://www.google.com
__ http://www.yahoo.com
__ http://www.rottentomatoes.com

Note

Note that there are two underscores following anonymous links/labels.

Admonitions

See also

this is a test of the seealso directive

Note

this is a test of the note directive

Warning

this is a test of the warning directive

These can be generated with the following code:

.. seealso:: this is a test of the **seealso** directive
.. note:: this is a test of the **note** directive
.. warning:: this is a test of the **warning** directive

.vimrc configurgation

If you use Vim as your text editor, edit your .vimrc to include the following macros for quickly making section headings.:

" reStructuredText files
au BufRead,BufNewFile *.rst set textwidth=80
let @h='yypVr=yykP'   " makes a section header (with overline)
let @o='yypVr='       " makes a section heading
let @i='yypVr-'       " makes a subsection heading
let @u='yypVr^'       " makes a subsubsection heading
let @f='gq}'          " format until next paragraph, fixes column widths