smotaal
7/19/2018 - 2:50 PM
ReStructuredText Examples
ReStructuredText Examples
<details>
<summary>Primer</summary>
A ReStructuredText Primer
=========================
:Author: Richard Jones
:Version: $Revision: 5801 $
: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
.. Note:: This document is an informal introduction to
reStructuredText. The `What Next?`_ section below has links to
further resources, including a formal reference.
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**``". This is called "inline markup".
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 lone asterisk * is handled just fine, as is the
asterisk in this equation: 5*6=30. 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
.. Tip:: Think of inline markup as a form of (parentheses) and use it
the same way: immediately before and after the text being marked
up. Inline markup by itself (surrounded by whitespace) or in the
middle of a word won't be recognized. See the `markup spec`__ for
full details.
__ ../../ref/rst/restructuredtext.html#inline-markup
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::
<section>
<title>
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/
</details>=====================================================
The reStructuredText_ Cheat Sheet: Syntax Reminders
=====================================================
:Info: See <http://docutils.sf.net/rst.html> for introductory docs.
:Author: David Goodger <goodger@python.org>
:Date: $Date: 2013-02-20 02:10:53 +0100 (Mi, 20. Feb 2013) $
:Revision: $Revision: 7612 $
:Description: This is a "docinfo block", or bibliographic field list
.. NOTE:: If you are reading this as HTML, please read
`<cheatsheet.txt>`_ instead to see the input syntax examples!
Section Structure
=================
Section titles are underlined or overlined & underlined.
Body Elements
=============
Grid table:
+--------------------------------+-----------------------------------+
| Paragraphs are flush-left, | Literal block, preceded by "::":: |
| separated by blank lines. | |
| | Indented |
| Block quotes are indented. | |
+--------------------------------+ or:: |
| >>> print 'Doctest block' | |
| Doctest block | > Quoted |
+--------------------------------+-----------------------------------+
| | Line blocks preserve line breaks & indents. [new in 0.3.6] |
| | Useful for addresses, verse, and adornment-free lists; long |
| lines can be wrapped with continuation lines. |
+--------------------------------------------------------------------+
Simple tables:
================ ============================================================
List Type Examples (syntax in the `text source <cheatsheet.txt>`_)
================ ============================================================
Bullet list * items begin with "-", "+", or "*"
Enumerated list 1. items use any variation of "1.", "A)", and "(i)"
#. also auto-enumerated
Definition list Term is flush-left : optional classifier
Definition is indented, no blank line between
Field list :field name: field body
Option list -o at least 2 spaces between option & description
================ ============================================================
================ ============================================================
Explicit Markup Examples (visible in the `text source`_)
================ ============================================================
Footnote .. [1] Manually numbered or [#] auto-numbered
(even [#labelled]) or [*] auto-symbol
Citation .. [CIT2002] A citation.
Hyperlink Target .. _reStructuredText: http://docutils.sf.net/rst.html
.. _indirect target: reStructuredText_
.. _internal target:
Anonymous Target __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html
Directive ("::") .. image:: images/biohazard.png
Substitution Def .. |substitution| replace:: like an inline directive
Comment .. is anything else
Empty Comment (".." on a line by itself, with blank lines before & after,
used to separate indentation contexts)
================ ============================================================
Inline Markup
=============
*emphasis*; **strong emphasis**; `interpreted text`; `interpreted text
with role`:emphasis:; ``inline literal text``; standalone hyperlink,
http://docutils.sourceforge.net; named reference, reStructuredText_;
`anonymous reference`__; footnote reference, [1]_; citation reference,
[CIT2002]_; |substitution|; _`inline internal target`.
Directive Quick Reference
=========================
See <http://docutils.sf.net/docs/ref/rst/directives.html> for full info.
================ ============================================================
Directive Name Description (Docutils version added to, in [brackets])
================ ============================================================
attention Specific admonition; also "caution", "danger",
"error", "hint", "important", "note", "tip", "warning"
admonition Generic titled admonition: ``.. admonition:: By The Way``
image ``.. image:: picture.png``; many options possible
figure Like "image", but with optional caption and legend
topic ``.. topic:: Title``; like a mini section
sidebar ``.. sidebar:: Title``; like a mini parallel document
parsed-literal A literal block with parsed inline markup
rubric ``.. rubric:: Informal Heading``
epigraph Block quote with class="epigraph"
highlights Block quote with class="highlights"
pull-quote Block quote with class="pull-quote"
compound Compound paragraphs [0.3.6]
container Generic block-level container element [0.3.10]
table Create a titled table [0.3.1]
list-table Create a table from a uniform two-level bullet list [0.3.8]
csv-table Create a table from CSV data [0.3.4]
contents Generate a table of contents
sectnum Automatically number sections, subsections, etc.
header, footer Create document decorations [0.3.8]
target-notes Create an explicit footnote for each external target
math Mathematical notation (input in LaTeX format)
meta HTML-specific metadata
include Read an external reST file as if it were inline
raw Non-reST data passed untouched to the Writer
replace Replacement text for substitution definitions
unicode Unicode character code conversion for substitution defs
date Generates today's date; for substitution defs
class Set a "class" attribute on the next element
role Create a custom interpreted text role [0.3.2]
default-role Set the default interpreted text role [0.3.10]
title Set the metadata document title [0.3.10]
================ ============================================================
Interpreted Text Role Quick Reference
=====================================
See <http://docutils.sf.net/docs/ref/rst/roles.html> for full info.
================ ============================================================
Role Name Description
================ ============================================================
emphasis Equivalent to *emphasis*
literal Equivalent to ``literal`` but processes backslash escapes
math Mathematical notation (input in LaTeX format)
PEP Reference to a numbered Python Enhancement Proposal
RFC Reference to a numbered Internet Request For Comments
raw For non-reST data; cannot be used directly (see docs) [0.3.6]
strong Equivalent to **strong**
sub Subscript
sup Superscript
title Title reference (book, etc.); standard default role
================ ============================================================Header 1
========
--------
Subtitle
--------
Example text.
.. contents:: Table of Contents
Header 2
--------
1. Blah blah ``code`` blah
2. More ``code``, hooray
3. Somé UTF-8°
The UTF-8 quote character in this table used to cause python to go boom. Now docutils just silently ignores it.
.. csv-table:: Things that are Awesome (on a scale of 1-11)
:quote: ”
Thing,Awesomeness
Icecream, 7
Honey Badgers, 10.5
Nickelback, -2
Iron Man, 10
Iron Man 2, 3
Tabular Data, 5
Made up ratings, 11
.. code::
A block of code
.. code:: python
python.code('hooray')
.. code:: javascript
export function ƒ(ɑ, β) {}
.. doctest:: ignored
>>> some_function()
'result'
>>> some_function()
'result'
============== ==========================================================
Travis http://travis-ci.org/tony/pullv
Docs http://pullv.rtfd.org
API http://pullv.readthedocs.org/en/latest/api.html
Issues https://github.com/tony/pullv/issues
Source https://github.com/tony/pullv
============== ==========================================================
.. image:: https://scan.coverity.com/projects/621/badge.svg
:target: https://scan.coverity.com/projects/621
:alt: Coverity Scan Build Status
.. image:: https://scan.coverity.com/projects/621/badge.svg
:alt: Coverity Scan Build Status
Field list
----------
:123456789 123456789 123456789 123456789 123456789 1: Uh-oh! This name is too long!
:123456789 123456789 123456789 123456789 1234567890: this is a long name,
but no problem!
:123456789 12345: this is not so long, but long enough for the default!
:123456789 1234: this should work even with the default :)
someone@somewhere.org
Press :kbd:`Ctrl+C` to quit
.. raw:: html
<p><strong>RAW HTML!</strong></p><style> p {color:blue;} </style>