| Author: | Kushal Das |
|---|---|
| Contact: | kushaldas@gmail.com |
| Date: | 2012-07-23 |
reStructuredText is plaintext that uses simple and intuitive constructs to indicate the structure of a document.
Open a new file called test.rst
$ vi test.rst
We will use this file for all our examples.
=================== Document Title Text ===================
The above will create the title of the document with Document Title Text as title.
We can have output in various formats. For our session we will use HTML. Use the following command to create test.html and view it in the browser.
$ rst2html test.rst test.html
Spaces are recommended for indentation. Blank lines are used to separate paragraphs. Multiple blank lines will be equivalent to a single blank line.
This is first paragraph. This is the second paragraph. This can continue in our example.
.. This is a comment .. _so: is this! .. [and] this! .. this:: too! .. |even| this:: !
Recomended characters to create section titles are
= - ` : . ' " ~ ^ _ * + #
Example section title
Section Title =============
Once a hierarchy of title styles is established, sections must use that hierarchy. We use this to create subsections.
Subsection Title ---------------- A paragraph for the subsection.
Re-generate the test.html file and see how it looks :)
A text block which begins with a "*", "+", "-", "•", "‣", or "⁃", followed by whitespace, is a bullet list item (a.k.a. "unordered" list item).
- Item 1 - Item 2 - Item 3 Not part of list.
They are similar to bullet lists but use enumerators instead of bullets. It contains enumeration sequence member and formatting, followed by whitespace.
1. Item 1 text 2. Item 2 text
To get auto-enumeration one can use #.
1. New item 1 #. New item 2 #. New item 3
Definition list item contains a term, optional classifiers, and a definition. A term is a simple one-line word or phrase. Optional classifiers may follow the term on the same line, each after an inline " : " (space, colon, space). A definition is a block indented relative to the term
Example
term 1
Definition 1.
term 2
Definition 2, paragraph 1.
term 3 : classifier
Definition 3.
Option lists are two-column lists of command-line options and descriptions, documenting a program's options.
-a Output all.
-b Output both (this description is
quite long).
-c arg Output just arg.
--long Output all day long.
Literal Blocks are the places where no markup processing is done.
::
for a in [5,4,3,2,1]: # this is program code, shown as-is
print a
print "it's..."
# a literal block continues until the indentation ends
Doctest blocks are interactive Python sessions cut-and-pasted into docstrings.
Normal plain text paragraph. >>> print 'this is a Doctest block' this is a Doctest block
We will use this a lot while commenting the source code we will write.
We can write simple tables like
===== ===== ======= A B A and B ===== ===== ======= False False False True False False False True False True True True ===== ===== =======
+------------------------+------------+----------+----------+ | 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. | +------------------------+------------+---------------------+
There are a few defined ways to create hyperlinks. Easiest way I find:
This is a `link <http://kushaldas.in>`_
We can create targeted hyperlinks
`Python programming language`_ is very nice for students. .. _Python programming language: http://python.org
We can use directives to create notes section.
.. note:: This is a note. - List item 1 - List item 2
For emphasis in the text we use *.
This is *emphasized text*.
This is an example of auto-numbered footnote.
Please RTFM [#]_ or you can read [#]_. .. [#] Read The Fine Manual .. [#] The next fine manual
?
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
Participate in dgplug Summer training