You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
552 lines
14 KiB
552 lines
14 KiB
.. This is a comment. Note how any initial comments are moved by |
|
transforms to after the document title, subtitle, and docinfo. |
|
|
|
================================ |
|
reStructuredText Demonstration |
|
================================ |
|
|
|
.. Above is the document title, and below is the subtitle. |
|
They are transformed from section titles after parsing. |
|
|
|
-------------------------------- |
|
Examples of Syntax Constructs |
|
-------------------------------- |
|
|
|
.. bibliographic fields (which also require a transform): |
|
|
|
:Author: David Goodger |
|
:Address: 123 Example Street |
|
Example, EX Canada |
|
A1B 2C3 |
|
:Contact: docutils-develop@lists.sourceforge.net |
|
:Authors: Me; Myself; I |
|
:organization: humankind |
|
:date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $ |
|
:status: This is a "work in progress" |
|
:revision: $Revision: 7302 $ |
|
:version: 1 |
|
:copyright: This document has been placed in the public domain. You |
|
may do with it as you wish. You may copy, modify, |
|
redistribute, reattribute, sell, buy, rent, lease, |
|
destroy, or improve it, quote it at length, excerpt, |
|
incorporate, collate, fold, staple, or mutilate it, or do |
|
anything else to it that your or anyone else's heart |
|
desires. |
|
:field name: This is a generic bibliographic field. |
|
:field name 2: |
|
Generic bibliographic fields may contain multiple body elements. |
|
|
|
Like this. |
|
|
|
:Dedication: |
|
|
|
For Docutils users & co-developers. |
|
|
|
:abstract: |
|
|
|
This document is a demonstration of the reStructuredText markup |
|
language, containing examples of all basic reStructuredText |
|
constructs and many advanced constructs. |
|
|
|
.. meta:: |
|
:keywords: reStructuredText, demonstration, demo, parser |
|
:description lang=en: A demonstration of the reStructuredText |
|
markup language, containing examples of all basic |
|
constructs and many advanced constructs. |
|
|
|
.. contents:: Table of Contents |
|
.. section-numbering:: |
|
|
|
|
|
Structural Elements |
|
=================== |
|
|
|
Section Title |
|
------------- |
|
|
|
That's it, the text just above this line. |
|
|
|
Transitions |
|
----------- |
|
|
|
Here's a transition: |
|
|
|
--------- |
|
|
|
It divides the section. |
|
|
|
Body Elements |
|
============= |
|
|
|
Paragraphs |
|
---------- |
|
|
|
A paragraph. |
|
|
|
Inline Markup |
|
````````````` |
|
|
|
Paragraphs contain text and may contain inline markup: *emphasis*, |
|
**strong emphasis**, ``inline literals``, standalone hyperlinks |
|
(http://www.python.org), external hyperlinks (Python_), internal |
|
cross-references (example_), external hyperlinks with embedded URIs |
|
(`Python web site <http://www.python.org>`__), footnote references |
|
(manually numbered [1]_, anonymous auto-numbered [#]_, labeled |
|
auto-numbered [#label]_, or symbolic [*]_), citation references |
|
([CIT2002]_), substitution references (|example|), and _`inline |
|
hyperlink targets` (see Targets_ below for a reference back to here). |
|
Character-level inline markup is also possible (although exceedingly |
|
ugly!) in *re*\ ``Structured``\ *Text*. Problems are indicated by |
|
|problematic| text (generated by processing errors; this one is |
|
intentional). |
|
|
|
The default role for interpreted text is `Title Reference`. Here are |
|
some explicit interpreted text roles: a PEP reference (:PEP:`287`); an |
|
RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`; |
|
and explicit roles for :emphasis:`standard` :strong:`inline` |
|
:literal:`markup`. |
|
|
|
.. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! |
|
|
|
Let's test wrapping and whitespace significance in inline literals: |
|
``This is an example of --inline-literal --text, --including some-- |
|
strangely--hyphenated-words. Adjust-the-width-of-your-browser-window |
|
to see how the text is wrapped. -- ---- -------- Now note the |
|
spacing between the words of this sentence (words |
|
should be grouped in pairs).`` |
|
|
|
If the ``--pep-references`` option was supplied, there should be a |
|
live link to PEP 258 here. |
|
|
|
Bullet Lists |
|
------------ |
|
|
|
- A bullet list |
|
|
|
+ Nested bullet list. |
|
+ Nested item 2. |
|
|
|
- Item 2. |
|
|
|
Paragraph 2 of item 2. |
|
|
|
* Nested bullet list. |
|
* Nested item 2. |
|
|
|
- Third level. |
|
- Item 2. |
|
|
|
* Nested item 3. |
|
|
|
Enumerated Lists |
|
---------------- |
|
|
|
1. Arabic numerals. |
|
|
|
a) lower alpha) |
|
|
|
(i) (lower roman) |
|
|
|
A. upper alpha. |
|
|
|
I) upper roman) |
|
|
|
2. Lists that don't start at 1: |
|
|
|
3. Three |
|
|
|
4. Four |
|
|
|
C. C |
|
|
|
D. D |
|
|
|
iii. iii |
|
|
|
iv. iv |
|
|
|
#. List items may also be auto-enumerated. |
|
|
|
Definition Lists |
|
---------------- |
|
|
|
Term |
|
Definition |
|
Term : classifier |
|
Definition paragraph 1. |
|
|
|
Definition paragraph 2. |
|
Term |
|
Definition |
|
|
|
Field Lists |
|
----------- |
|
|
|
:what: Field lists map field names to field bodies, like database |
|
records. They are often part of an extension syntax. They are |
|
an unambiguous variant of RFC 2822 fields. |
|
|
|
:how arg1 arg2: |
|
|
|
The field marker is a colon, the field name, and a colon. |
|
|
|
The field body may contain one or more body elements, indented |
|
relative to the field marker. |
|
|
|
Option Lists |
|
------------ |
|
|
|
For listing command-line options: |
|
|
|
-a command-line option "a" |
|
-b file options can have arguments |
|
and long descriptions |
|
--long options can be long also |
|
--input=file long options can also have |
|
arguments |
|
|
|
--very-long-option |
|
The description can also start on the next line. |
|
|
|
The description may contain multiple body elements, |
|
regardless of where it starts. |
|
|
|
-x, -y, -z Multiple options are an "option group". |
|
-v, --verbose Commonly-seen: short & long options. |
|
-1 file, --one=file, --two file |
|
Multiple options with arguments. |
|
/V DOS/VMS-style options too |
|
|
|
There must be at least two spaces between the option and the |
|
description. |
|
|
|
Literal Blocks |
|
-------------- |
|
|
|
Literal blocks are indicated with a double-colon ("::") at the end of |
|
the preceding paragraph (over there ``-->``). They can be indented:: |
|
|
|
if literal_block: |
|
text = 'is left as-is' |
|
spaces_and_linebreaks = 'are preserved' |
|
markup_processing = None |
|
|
|
Or they can be quoted without indentation:: |
|
|
|
>> Great idea! |
|
> |
|
> Why didn't I think of that? |
|
|
|
Line Blocks |
|
----------- |
|
|
|
| This is a line block. It ends with a blank line. |
|
| Each new line begins with a vertical bar ("|"). |
|
| Line breaks and initial indents are preserved. |
|
| Continuation lines are wrapped portions of long lines; |
|
they begin with a space in place of the vertical bar. |
|
| The left edge of a continuation line need not be aligned with |
|
the left edge of the text above it. |
|
|
|
| This is a second line block. |
|
| |
|
| Blank lines are permitted internally, but they must begin with a "|". |
|
|
|
Take it away, Eric the Orchestra Leader! |
|
|
|
| A one, two, a one two three four |
|
| |
|
| Half a bee, philosophically, |
|
| must, *ipso facto*, half not be. |
|
| But half the bee has got to be, |
|
| *vis a vis* its entity. D'you see? |
|
| |
|
| But can a bee be said to be |
|
| or not to be an entire bee, |
|
| when half the bee is not a bee, |
|
| due to some ancient injury? |
|
| |
|
| Singing... |
|
|
|
Block Quotes |
|
------------ |
|
|
|
Block quotes consist of indented body elements: |
|
|
|
My theory by A. Elk. Brackets Miss, brackets. This theory goes |
|
as follows and begins now. All brontosauruses are thin at one |
|
end, much much thicker in the middle and then thin again at the |
|
far end. That is my theory, it is mine, and belongs to me and I |
|
own it, and what it is too. |
|
|
|
-- Anne Elk (Miss) |
|
|
|
Doctest Blocks |
|
-------------- |
|
|
|
>>> print 'Python-specific usage examples; begun with ">>>"' |
|
Python-specific usage examples; begun with ">>>" |
|
>>> print '(cut and pasted from interactive Python sessions)' |
|
(cut and pasted from interactive Python sessions) |
|
|
|
Tables |
|
------ |
|
|
|
Here's a grid table followed by a simple table: |
|
|
|
+------------------------+------------+----------+----------+ |
|
| Header row, column 1 | Header 2 | Header 3 | Header 4 | |
|
| (header rows optional) | | | | |
|
+========================+============+==========+==========+ |
|
| body row 1, column 1 | column 2 | column 3 | column 4 | |
|
+------------------------+------------+----------+----------+ |
|
| body row 2 | Cells may span columns. | |
|
+------------------------+------------+---------------------+ |
|
| body row 3 | Cells may | - Table cells | |
|
+------------------------+ span rows. | - contain | |
|
| body row 4 | | - body elements. | |
|
+------------------------+------------+----------+----------+ |
|
| body row 5 | Cells may also be | | |
|
| | empty: ``-->`` | | |
|
+------------------------+-----------------------+----------+ |
|
|
|
===== ===== ====== |
|
Inputs Output |
|
------------ ------ |
|
A B A or B |
|
===== ===== ====== |
|
False False False |
|
True False True |
|
False True True |
|
True True True |
|
===== ===== ====== |
|
|
|
Footnotes |
|
--------- |
|
|
|
.. [1] A footnote contains body elements, consistently indented by at |
|
least 3 spaces. |
|
|
|
This is the footnote's second paragraph. |
|
|
|
.. [#label] Footnotes may be numbered, either manually (as in [1]_) or |
|
automatically using a "#"-prefixed label. This footnote has a |
|
label so it can be referred to from multiple places, both as a |
|
footnote reference ([#label]_) and as a hyperlink reference |
|
(label_). |
|
|
|
.. [#] This footnote is numbered automatically and anonymously using a |
|
label of "#" only. |
|
|
|
.. [*] Footnotes may also use symbols, specified with a "*" label. |
|
Here's a reference to the next footnote: [*]_. |
|
|
|
.. [*] This footnote shows the next symbol in the sequence. |
|
|
|
.. [4] Here's an unreferenced footnote, with a reference to a |
|
nonexistent footnote: [5]_. |
|
|
|
Citations |
|
--------- |
|
|
|
.. [CIT2002] Citations are text-labeled footnotes. They may be |
|
rendered separately and differently from footnotes. |
|
|
|
Here's a reference to the above, [CIT2002]_, and a [nonexistent]_ |
|
citation. |
|
|
|
Targets |
|
------- |
|
|
|
.. _example: |
|
|
|
This paragraph is pointed to by the explicit "example" target. A |
|
reference can be found under `Inline Markup`_, above. `Inline |
|
hyperlink targets`_ are also possible. |
|
|
|
Section headers are implicit targets, referred to by name. See |
|
Targets_, which is a subsection of `Body Elements`_. |
|
|
|
Explicit external targets are interpolated into references such as |
|
"Python_". |
|
|
|
.. _Python: http://www.python.org/ |
|
|
|
Targets may be indirect and anonymous. Thus `this phrase`__ may also |
|
refer to the Targets_ section. |
|
|
|
__ Targets_ |
|
|
|
Here's a `hyperlink reference without a target`_, which generates an |
|
error. |
|
|
|
Duplicate Target Names |
|
`````````````````````` |
|
|
|
Duplicate names in section headers or other implicit targets will |
|
generate "info" (level-1) system messages. Duplicate names in |
|
explicit targets will generate "warning" (level-2) system messages. |
|
|
|
Duplicate Target Names |
|
`````````````````````` |
|
|
|
Since there are two "Duplicate Target Names" section headers, we |
|
cannot uniquely refer to either of them by name. If we try to (like |
|
this: `Duplicate Target Names`_), an error is generated. |
|
|
|
Directives |
|
---------- |
|
|
|
.. contents:: :local: |
|
|
|
These are just a sample of the many reStructuredText Directives. For |
|
others, please see |
|
http://docutils.sourceforge.net/docs/ref/rst/directives.html. |
|
|
|
Document Parts |
|
`````````````` |
|
|
|
An example of the "contents" directive can be seen above this section |
|
(a local, untitled table of contents_) and at the beginning of the |
|
document (a document-wide `table of contents`_). |
|
|
|
Images |
|
`````` |
|
|
|
An image directive (also clickable -- a hyperlink reference): |
|
|
|
.. image:: images/title.png |
|
:target: directives_ |
|
|
|
A figure directive: |
|
|
|
.. figure:: images/title.png |
|
:alt: reStructuredText, the markup syntax |
|
|
|
A figure is an image with a caption and/or a legend: |
|
|
|
+------------+-----------------------------------------------+ |
|
| re | Revised, revisited, based on 're' module. | |
|
+------------+-----------------------------------------------+ |
|
| Structured | Structure-enhanced text, structuredtext. | |
|
+------------+-----------------------------------------------+ |
|
| Text | Well it is, isn't it? | |
|
+------------+-----------------------------------------------+ |
|
|
|
This paragraph is also part of the legend. |
|
|
|
Admonitions |
|
``````````` |
|
|
|
.. Attention:: Directives at large. |
|
|
|
.. Caution:: |
|
|
|
Don't take any wooden nickels. |
|
|
|
.. DANGER:: Mad scientist at work! |
|
|
|
.. Error:: Does not compute. |
|
|
|
.. Hint:: It's bigger than a bread box. |
|
|
|
.. Important:: |
|
- Wash behind your ears. |
|
- Clean up your room. |
|
- Call your mother. |
|
- Back up your data. |
|
|
|
.. Note:: This is a note. |
|
|
|
.. Tip:: 15% if the service is good. |
|
|
|
.. WARNING:: Strong prose may provoke extreme mental exertion. |
|
Reader discretion is strongly advised. |
|
|
|
.. admonition:: And, by the way... |
|
|
|
You can make up your own admonition too. |
|
|
|
Topics, Sidebars, and Rubrics |
|
````````````````````````````` |
|
|
|
.. sidebar:: Sidebar Title |
|
:subtitle: Optional Subtitle |
|
|
|
This is a sidebar. It is for text outside the flow of the main |
|
text. |
|
|
|
.. rubric:: This is a rubric inside a sidebar |
|
|
|
Sidebars often appears beside the main text with a border and |
|
background color. |
|
|
|
.. topic:: Topic Title |
|
|
|
This is a topic. |
|
|
|
.. rubric:: This is a rubric |
|
|
|
Target Footnotes |
|
```````````````` |
|
|
|
.. target-notes:: |
|
|
|
Replacement Text |
|
```````````````` |
|
|
|
I recommend you try |Python|_. |
|
|
|
.. |Python| replace:: Python, *the* best language around |
|
|
|
Compound Paragraph |
|
`````````````````` |
|
|
|
.. compound:: |
|
|
|
This paragraph contains a literal block:: |
|
|
|
Connecting... OK |
|
Transmitting data... OK |
|
Disconnecting... OK |
|
|
|
and thus consists of a simple paragraph, a literal block, and |
|
another simple paragraph. Nonetheless it is semantically *one* |
|
paragraph. |
|
|
|
This construct is called a *compound paragraph* and can be produced |
|
with the "compound" directive. |
|
|
|
Substitution Definitions |
|
------------------------ |
|
|
|
An inline image (|example|) example: |
|
|
|
.. |EXAMPLE| image:: images/biohazard.png |
|
|
|
(Substitution definitions are not visible in the HTML source.) |
|
|
|
Comments |
|
-------- |
|
|
|
Here's one: |
|
|
|
.. Comments begin with two dots and a space. Anything may |
|
follow, except for the syntax of footnotes, hyperlink |
|
targets, directives, or substitution definitions. |
|
|
|
Double-dashes -- "--" -- must be escaped somehow in HTML output. |
|
|
|
(View the HTML source to see the comment.) |
|
|
|
Error Handling |
|
============== |
|
|
|
Any errors caught during processing will generate system messages. |
|
|
|
|*** Expect 6 errors (including this one). ***| |
|
|
|
There should be six messages in the following, auto-generated |
|
section, "Docutils System Messages": |
|
|
|
.. section should be added by Docutils automatically
|
|
|