ReST Primer


A ReStructuredText Primer
=========================

:Author: Richard Jones
:Version: $Revision: 4350 $
:Copyright: This document has been placed in the public domain.

.. contents::


The text below contains links that look like "(quickref__)".  These
are relative links that point to the `Quick reStructuredText`_ user
reference.  If these links don't work, please refer to the `master
quick reference`_ document.

__
.. _Quick reStructuredText: quickref.html
.. _master quick reference:
   http://docutils.sourceforge.net/docs/user/rst/quickref.html


Structure
---------

From the outset, let me say that "Structured Text" is probably a bit
of a misnomer.  It's more like "Relaxed Text" that uses certain
consistent patterns.  These patterns are interpreted by a HTML
converter to produce "Very Structured Text" that can be used by a web
browser.

The most basic pattern recognised is a **paragraph** (quickref__).
That's a chunk of text that is separated by blank lines (one is
enough).  Paragraphs must have the same indentation -- that is, line
up at their left edge.  Paragraphs that start indented will result in
indented quote paragraphs. For 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.

Results in:

  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.

__ quickref.html#paragraphs


Text styles
-----------

(quickref__)

__ quickref.html#inline-markup

Inside paragraphs and other bodies of text, you may additionally mark
text for *italics* with "``*italics*``" or **bold** with
"``**bold**``".

If you want something to appear as a fixed-space literal, use
"````double back-quotes````".  Note that no further fiddling is done
inside the double back-quotes -- so asterisks "``*``" etc. are left
alone.

If you find that you want to use one of the "special" characters in
text, it will generally be OK -- reStructuredText is pretty smart.
For example, this * asterisk is handled just fine.  If you actually
want text \*surrounded by asterisks* to **not** be italicised, then
you need to indicate that the asterisk is not special.  You do this by
placing a backslash just before it, like so "``\*``" (quickref__), or
by enclosing it in double back-quotes (inline literals), like this::

    ``\*``

__ quickref.html#escaping


Lists
-----

Lists of items come in three main flavours: **enumerated**,
**bulleted** and **definitions**.  In all list cases, you may have as
many paragraphs, sublists, etc. as you want, as long as the left-hand
side of the paragraph or whatever aligns with the first line of text
in the list item.

Lists must always start a new paragraph -- that is, they must appear
after a blank line.

**enumerated** lists (numbers, letters or roman numerals; quickref__)
  __ quickref.html#enumerated-lists

  Start a line off with a number or letter followed by a period ".",
  right bracket ")" or surrounded by brackets "( )" -- whatever you're
  comfortable with.  All of the following forms are recognised::

    1. numbers

    A. upper-case letters
       and it goes over many lines

       with two paragraphs and all!

    a. lower-case letters

       3. with a sub-list starting at a different number
       4. make sure the numbers are in the correct sequence though!

    I. upper-case roman numerals

    i. lower-case roman numerals

    (1) numbers again

    1) and again

  Results in (note: the different enumerated list styles are not
  always supported by every web browser, so you may not get the full
  effect here):

  1. numbers

  A. upper-case letters
     and it goes over many lines

     with two paragraphs and all!

  a. lower-case letters

     3. with a sub-list starting at a different number
     4. make sure the numbers are in the correct sequence though!

  I. upper-case roman numerals

  i. lower-case roman numerals

  (1) numbers again

  1) and again

**bulleted** lists (quickref__)
  __ quickref.html#bullet-lists

  Just like enumerated lists, start the line off with a bullet point
  character - either "-", "+" or "*"::

    * a bullet point using "*"

      - a sub-list using "-"

        + yet another sub-list

      - another item

  Results in:

  * a bullet point using "*"

    - a sub-list using "-"

      + yet another sub-list

    - another item

**definition** lists (quickref__)
  __ quickref.html#definition-lists

  Unlike the other two, the definition lists consist of a term, and
  the definition of that term.  The format of a definition list is::

    what
      Definition lists associate a term with a definition.

    *how*
      The term is a one-line phrase, and the definition is one or more
      paragraphs or body elements, indented relative to the term.
      Blank lines are not allowed between term and definition.

  Results in:

  what
    Definition lists associate a term with a definition.

  *how*
    The term is a one-line phrase, and the definition is one or more
    paragraphs or body elements, indented relative to the term.
    Blank lines are not allowed between term and definition.


Preformatting (code samples)
----------------------------
(quickref__)

__ quickref.html#literal-blocks

To just include a chunk of preformatted, never-to-be-fiddled-with
text, finish the prior paragraph with "``::``".  The preformatted
block is finished when the text falls back to the same indentation
level as a paragraph prior to the preformatted block.  For example::

  An example::

      Whitespace, newlines, blank lines, and all kinds of markup
        (like *this* or \this) is preserved by literal blocks.
    Lookie here, I've dropped an indentation level
    (but not far enough)

  no more example

Results in:

  An example::

      Whitespace, newlines, blank lines, and all kinds of markup
        (like *this* or \this) is preserved by literal blocks.
    Lookie here, I've dropped an indentation level
    (but not far enough)

  no more example

Note that if a paragraph consists only of "``::``", then it's removed
from the output::

  ::

      This is preformatted text, and the
      last "::" paragraph is removed

Results in:

::

    This is preformatted text, and the
    last "::" paragraph is removed


Sections
--------

(quickref__)

__ quickref.html#section-structure

To break longer text up into sections, you use **section headers**.
These are a single line of text (one or more words) with adornment: an
underline alone, or an underline and an overline together, in dashes
"``-----``", equals "``======``", tildes "``~~~~~~``" or any of the
non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you
feel comfortable with.  An underline-only adornment is distinct from
an overline-and-underline adornment using the same character.  The
underline/overline must be at least as long as the title text.  Be
consistent, since all sections marked with the same adornment style
are deemed to be at the same level::

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

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

  Subsection 1.1.1 Title
  ~~~~~~~~~~~~~~~~~~~~~~

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

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

This results in the following structure, illustrated by simplified
pseudo-XML::

    
Chapter 1 Title <section> <title> Section 1.1 Title <section> <title> Subsection 1.1.1 Title <section> <title> Section 1.2 Title <section> <title> Chapter 2 Title (Pseudo-XML uses indentation for nesting and has no end-tags. It's not possible to show actual processed output, as in the other examples, because sections cannot exist inside block quotes. For a concrete example, compare the section structure of this document's source text and processed output.) Note that section headers are available as link targets, just using their name. To link to the Lists_ heading, I write "``Lists_``". If the heading has a space in it like `text styles`_, we need to quote the heading "```text styles`_``". Document Title / Subtitle ````````````````````````` The title of the whole document is distinct from section titles and may be formatted somewhat differently (e.g. the HTML writer by default shows it as a centered heading). To indicate the document title in reStructuredText, use a unique adornment style at the beginning of the document. To indicate the document subtitle, use another unique adornment style immediately after the document title. For example:: ================ Document Title ================ ---------- Subtitle ---------- Section Title ============= ... Note that "Document Title" and "Section Title" above both use equals signs, but are distict and unrelated styles. The text of overline-and-underlined titles (but not underlined-only) may be inset for aesthetics. Images ------ (quickref__) __ quickref.html#directives To include an image in your document, you use the the ``image`` directive__. For example:: .. image:: images/biohazard.png results in: .. image:: images/biohazard.png The ``images/biohazard.png`` part indicates the filename of the image you wish to appear in the document. There's no restriction placed on the image (format, size etc). If the image is to appear in HTML and you wish to supply additional information, you may:: .. image:: images/biohazard.png :height: 100 :width: 200 :scale: 50 :alt: alternate text See the full `image directive documentation`__ for more info. __ ../../ref/rst/directives.html __ ../../ref/rst/directives.html#images What Next? ---------- This primer introduces the most common features of reStructuredText, but there are a lot more to explore. The `Quick reStructuredText`_ user reference is a good place to go next. For complete details, the `reStructuredText Markup Specification`_ is the place to go [#]_. Users who have questions or need assistance with Docutils or reStructuredText should post a message to the Docutils-users_ mailing list. .. [#] If that relative link doesn't work, try the master document: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html. .. _reStructuredText Markup Specification: ../../ref/rst/restructuredtext.html .. _Docutils-users: ../mailing-lists.html#docutils-users .. _Docutils project web site: http://docutils.sourceforge.net/ </pre> <div class="sharedaddy sd-sharing-enabled"><div class="robots-nocontent sd-block sd-social sd-social-icon sd-sharing"><h3 class="sd-title">Share this:</h3><div class="sd-content"><ul><li class="share-facebook"><a rel="nofollow" data-shared="sharing-facebook-2007" class="share-facebook sd-button share-icon no-text" href="http://johnlaudun.org/20080407-rest-primer/?share=facebook" target="_blank" title="Click to share on Facebook"><span></span><span class="sharing-screen-reader-text">Click to share on Facebook (Opens in new window)</span></a></li><li class="share-twitter"><a rel="nofollow" data-shared="sharing-twitter-2007" class="share-twitter sd-button share-icon no-text" href="http://johnlaudun.org/20080407-rest-primer/?share=twitter" target="_blank" title="Click to share on Twitter"><span></span><span class="sharing-screen-reader-text">Click to share on Twitter (Opens in new window)</span></a></li><li class="share-linkedin"><a rel="nofollow" data-shared="sharing-linkedin-2007" class="share-linkedin sd-button share-icon no-text" href="http://johnlaudun.org/20080407-rest-primer/?share=linkedin" target="_blank" title="Click to share on LinkedIn"><span></span><span class="sharing-screen-reader-text">Click to share on LinkedIn (Opens in new window)</span></a></li><li class="share-reddit"><a rel="nofollow" data-shared="" class="share-reddit sd-button share-icon no-text" href="http://johnlaudun.org/20080407-rest-primer/?share=reddit" target="_blank" title="Click to share on Reddit"><span></span><span class="sharing-screen-reader-text">Click to share on Reddit (Opens in new window)</span></a></li><li class="share-google-plus-1"><a rel="nofollow" data-shared="sharing-google-2007" class="share-google-plus-1 sd-button share-icon no-text" href="http://johnlaudun.org/20080407-rest-primer/?share=google-plus-1" target="_blank" title="Click to share on Google+"><span></span><span class="sharing-screen-reader-text">Click to share on Google+ (Opens in new window)</span></a></li><li class="share-email"><a rel="nofollow" data-shared="" class="share-email sd-button share-icon no-text" href="http://johnlaudun.org/20080407-rest-primer/?share=email" target="_blank" title="Click to email this to a friend"><span></span><span class="sharing-screen-reader-text">Click to email this to a friend (Opens in new window)</span></a></li><li class="share-print"><a rel="nofollow" data-shared="" class="share-print sd-button share-icon no-text" href="http://johnlaudun.org/20080407-rest-primer/#print" target="_blank" title="Click to print"><span></span><span class="sharing-screen-reader-text">Click to print (Opens in new window)</span></a></li><li class="share-end"></li></ul></div></div></div> <div id='jp-relatedposts' class='jp-relatedposts' > <h3 class="jp-relatedposts-headline"><em>Related</em></h3> </div> </div><!-- .entry-content --> <footer class="entry-meta"> Posted on <a href="http://johnlaudun.org/20080407-rest-primer/" title="10:10" rel="bookmark"><time class="entry-date" datetime="2008-04-07T10:10:05+00:00" pubdate>2008 April 7</time></a><span class="byline"> by <span class="author vcard"><a class="url fn n" href="http://johnlaudun.org/author/johnlaudun/" title="View all posts by johnlaudun" rel="author">johnlaudun</a></span></span>. This entry was posted in <a href="http://johnlaudun.org/category/work/" rel="category tag">work</a> and tagged <a href="http://johnlaudun.org/tag/text/" rel="tag">text</a>. Bookmark the <a href="http://johnlaudun.org/20080407-rest-primer/" title="Permalink to ReST Primer" rel="bookmark">permalink</a>. </footer><!-- .entry-meta --> </article><!-- #post-2007 --> <nav role="navigation" id="nav-below" class="site-navigation post-navigation"> <h1 class="assistive-text">Post navigation</h1> <div class="nav-previous"><a href="http://johnlaudun.org/20080329-a-new-language/" rel="prev"><span class="meta-nav">←</span> A New Language</a></div> <div class="nav-next"><a href="http://johnlaudun.org/20080408-more-new-language/" rel="next">More New Language <span class="meta-nav">→</span></a></div> </nav><!-- #nav-below --> </div><!-- #content .site-content --> </div><!-- #primary .content-area --> <div id="secondary" class="widget-area" role="complementary"> <aside id="search-5" class="widget widget_search"> <form method="get" id="searchform" action="http://johnlaudun.org/" role="search"> <label for="s" class="assistive-text">Search</label> <input type="text" class="field" name="s" value="" id="s" placeholder="Search …" /> <input type="submit" class="submit" name="submit" id="searchsubmit" value="Search" /> </form> </aside><aside id="text-3" class="widget widget_text"> <div class="textwidget"><a href="http://johnlaudun.org/boat/" rel="attachment wp-att-7877"><img src="https://i0.wp.com/media.johnlaudun.org.s3.amazonaws.com/wordpress/media/2016/01/ACB-cover-small-103x150.jpeg?resize=103%2C150" alt="The Amazing Crawfish Boat" data-recalc-dims="1" /></a> <p style="line-height:1.1 "><small><em>The Amazing Crawfish Boat</em> is available at your favorite bookseller (both <a href="http://amzn.to/1rf9wAT">Amazon</a> and <a href="http://www.barnesandnoble.com/w/the-amazing-crawfish-boat-john-laudun/1121843205?ean=9781496804204">B&N</a>). I have also released some additional <em>free</em> materials: audio versions of some of the chapters and photos — all available for download. Details are available on the <a href="http://johnlaudun.org/boat/">book’s page</a>.</small></p></div> </aside><aside id="top-posts-2" class="widget widget_top-posts"><h1 class="widget-title">Top Posts</h1><ul> <li> <a href="http://johnlaudun.org/20131228-ipython-notebook-keyboard-shortcuts/" class="bump-view" data-bump-view="tp"> iPython Notebook Keyboard Shortcuts </a> </li> <li> <a href="http://johnlaudun.org/20150512-installing-and-setting-pip-with-macports/" class="bump-view" data-bump-view="tp"> Installing, and Setting, PIP with MacPorts </a> </li> <li> <a href="http://johnlaudun.org/20151127-clouds/" class="bump-view" data-bump-view="tp"> Clouds </a> </li> <li> <a href="http://johnlaudun.org/20130126-nltk-stopwords/" class="bump-view" data-bump-view="tp"> NLTK and Stopwords </a> </li> <li> <a href="http://johnlaudun.org/20170228-open-source-tools-for-nlp/" class="bump-view" data-bump-view="tp"> Open Source Tools for NLP </a> </li> </ul></aside> </div><!-- #secondary .widget-area --> </div><!-- #main .site-main --> <footer id="colophon" class="site-footer" role="contentinfo"> <div class="site-info"> <a href="http://wordpress.org/" rel="generator">Proudly powered by WordPress</a> Theme: Publish by <a href="http://kovshenin.com/" rel="designer">Konstantin Kovshenin</a>. </div><!-- .site-info --> </footer><!-- #colophon .site-footer --> </div><!-- #page .hfeed .site --> <div style="display:none"> </div> <script> jQuery(document).ready(function () { jQuery.post('http://johnlaudun.org?ga_action=googleanalytics_get_script', {action: 'googleanalytics_get_script'}, function(response) { var F = new Function ( response ); return( F() ); }); }); </script> <script type="text/javascript"> window.WPCOM_sharing_counts = {"http:\/\/johnlaudun.org\/20080407-rest-primer\/":2007}; </script> <div id="sharing_email" style="display: none;"> <form action="/20080407-rest-primer/" method="post"> <label for="target_email">Send to Email Address</label> <input type="email" name="target_email" id="target_email" value="" /> <label for="source_name">Your Name</label> <input type="text" name="source_name" id="source_name" value="" /> <label for="source_email">Your Email Address</label> <input type="email" name="source_email" id="source_email" value="" /> <input type="text" id="jetpack-source_f_name" name="source_f_name" class="input" value="" size="25" autocomplete="off" title="This field is for validation and should not be changed" /> <script>jQuery( document ).ready( function(){ document.getElementById('jetpack-source_f_name').value = '' });</script> <img style="float: right; display: none" class="loading" src="http://johnlaudun.org/wordpress/wp-content/plugins/jetpack/modules/sharedaddy/images/loading.gif" alt="loading" width="16" height="16" /> <input type="submit" value="Send Email" class="sharing_send" /> <a rel="nofollow" href="#cancel" class="sharing_cancel">Cancel</a> <div class="errors errors-1" style="display: none;"> Post was not sent - check your email addresses! </div> <div class="errors errors-2" style="display: none;"> Email check failed, please try again </div> <div class="errors errors-3" style="display: none;"> Sorry, your blog cannot share posts by email. </div> </form> </div> <script type='text/javascript' src='http://johnlaudun.org/wordpress/wp-content/plugins/jetpack/modules/photon/photon.js?ver=20130122'></script> <script type='text/javascript' src='https://s0.wp.com/wp-content/js/devicepx-jetpack.js?ver=201747'></script> <script type='text/javascript' src='http://s.gravatar.com/js/gprofiles.js?ver=2017Novaa'></script> <script type='text/javascript'> /* <![CDATA[ */ var WPGroHo = {"my_hash":""}; /* ]]> */ </script> <script type='text/javascript' src='http://johnlaudun.org/wordpress/wp-content/plugins/jetpack/modules/wpgroho.js?ver=4.8.3'></script> <script type='text/javascript' src='http://johnlaudun.org/wordpress/wp-content/themes/publish/js/small-menu.js?ver=20120206'></script> <script type='text/javascript' src='http://johnlaudun.org/wordpress/wp-includes/js/wp-embed.min.js?ver=4.8.3'></script> <script type='text/javascript'> /* <![CDATA[ */ var sharing_js_options = {"lang":"en","counts":"1"}; /* ]]> */ </script> <script type='text/javascript' src='http://johnlaudun.org/wordpress/wp-content/plugins/jetpack/modules/sharedaddy/sharing.js?ver=5.3'></script> <script type='text/javascript'> var windowOpen; jQuery( document.body ).on( 'click', 'a.share-facebook', function() { // If there's another sharing window open, close it. if ( 'undefined' !== typeof windowOpen ) { windowOpen.close(); } windowOpen = window.open( jQuery( this ).attr( 'href' ), 'wpcomfacebook', 'menubar=1,resizable=1,width=600,height=400' ); return false; }); var windowOpen; jQuery( document.body ).on( 'click', 'a.share-twitter', function() { // If there's another sharing window open, close it. if ( 'undefined' !== typeof windowOpen ) { windowOpen.close(); } windowOpen = window.open( jQuery( this ).attr( 'href' ), 'wpcomtwitter', 'menubar=1,resizable=1,width=600,height=350' ); return false; }); var windowOpen; jQuery( document.body ).on( 'click', 'a.share-linkedin', function() { // If there's another sharing window open, close it. if ( 'undefined' !== typeof windowOpen ) { windowOpen.close(); } windowOpen = window.open( jQuery( this ).attr( 'href' ), 'wpcomlinkedin', 'menubar=1,resizable=1,width=580,height=450' ); return false; }); var windowOpen; jQuery( document.body ).on( 'click', 'a.share-google-plus-1', function() { // If there's another sharing window open, close it. if ( 'undefined' !== typeof windowOpen ) { windowOpen.close(); } windowOpen = window.open( jQuery( this ).attr( 'href' ), 'wpcomgoogle-plus-1', 'menubar=1,resizable=1,width=480,height=550' ); return false; }); </script> <script type='text/javascript' src='https://stats.wp.com/e-201747.js' async defer></script> <script type='text/javascript'> _stq = window._stq || []; _stq.push([ 'view', {v:'ext',j:'1:5.3',blog:'33779968',post:'2007',tz:'-6',srv:'johnlaudun.org'} ]); _stq.push([ 'clickTrackerInit', '33779968', '2007' ]); </script> </body> </html>