mirror of
https://github.com/ThePhD/sol2.git
synced 2024-03-22 13:10:44 +08:00
Add demo.txt from docutils project to demo. Add it as a page to toc.
This commit is contained in:
Tony Narlock
parent
e30cc2e2af
commit
e38f44c85d
554
demo_docs/source/demo.rst
Normal file
554
demo_docs/source/demo.rst
Normal file
|
|
@ -0,0 +1,554 @@
|
|||
.. 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 19:23:53 +0000 (Tue, 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
|
||||
|
||||
demo.rst from: http://docutils.sourceforge.net/docs/user/rst/demo.txt
|
||||
|
|
@ -12,6 +12,8 @@ Contents:
|
|||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
demo
|
||||
|
||||
Maaaaath!
|
||||
=========
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user