.. _rst-primer:

======================================
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 :ref:`rst-vimrc-configuration` to
make writing documentation easier.

__ http://sphinx-doc.org/rest.html
__ http://docutils.sourceforge.net/rst.html
__ http://docutils.sourceforge.net/docs/user/rst/quickstart.html

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!

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

::

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

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

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

.. _rst-vimrc-configuration:

.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