reStructuredText¶

Inline Markup¶

*text*   : italics
**text** : boldface
``text`` : code samples/blocks, verbatim mode - used as the escaping character
|        : vertical bar '|' for line break
thisis\ *one*\ word : use of backslash to intreprete a single word in different formats
`sphinx <http://www.sphinx-doc.org>`_ : create links to internal or external web pages

Headings¶

# with overline, for parts
* with overline, for chapters
=, for sections
-, for subsections
^, for subsubsections
“, for paragraphs

Colored Boxes¶

[ note, seealso, todo and warnings]

.. note::  This is a **note** box.

Note

This is a note box.

.. seealso:: This is a simple **seealso** note.

Lists and Quote-like blocks¶

Bullet List(* ), Numbered List(numbers or #. )

* List 1
* List 2

1. List 1
2. List 2

#. List 1
#. List 2

Nested lists: separated from the parent list items by blank lines

* this is
* a list

    * with a nested list
    * and some subitems

* and here the parent list continues

Term¶

one-line word or phrase,
multiple paragraphs,
no blank line between a term line and a definition block

term 1
 Definition 1.

term 2
    Definition 2, paragraph 1.

    Definition 2, paragraph 2.

term 3 : classifier
    Definition 3.

term 4 : classifier one : classifier two
    Definition 4

Directives¶

A reST directive is like a function – a powerful construct of the reST syntax used to include formatted text, and it accepts:

arguments
options
body

.. code-block:: html
   :linenos:

   <h1>Code Block</h1>

code-block directive: html (argument), linenos (option) toctree directive: maxdepth (option - indicating maximum number of levels in a single menu)

Code and Literal Blocks¶

ending a paragraph with the special marker ::

preceded by whitespace -> marker is removed
preceded by non-whitespace -> marker is replaced by a single colon
if continued with a same paragraph without a blank line, it is completely left out of the document

Table Example¶

grid, simple, csv, list-table syntax
tabularcolumns directive (column spec - to determine column width (default is left-aligned)

Example 1:

==================   ============
Name                 Age
==================   ============
John D Hunter        40
Cast of Thousands    41
And Still More       42
==================   ============

Example 2:

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |
+------------+------------+-----------+

Header 1	Header 2	Header 3
body row 1	column 2	column 3
body row 2	Cells may span columns.
body row 3	Cells may span rows.	Cells contain blocks.
body row 4	Cells may span rows.	Cells contain blocks.

Example 3:

.. tabularcolumns:: |l|c|p{5cm}|

+--------------+---+-----------+
|simple text   | 2 | 3         |
+--------------+---+-----------+

Example 4

.. |insta| image:: ../path/to/image
       :width: 50pt
       :height: 30pt

.. |twit| image:: ../path/to/image
       :width: 30pt
       :height: 30pt

+---------------------+----------------+
|  |insta|            |   |twit|       |
+---------------------+----------------+

CSV Example:

.. csv-table:: csv-example
   :header: "Fullname", "Address"
   :widths: 20, 20

   "User A", "Lalitpur,"
   "User B", "Kathmandu"

Hyperlinks¶

External Links
Internal Links (Cross referencing locations)
- Implicit Links to Title
- Explicit Links

External Links

`<http://www.sphinx-doc.org>`_

    `Sphinx Documentation <http://www.sphinx-doc.org>`_
(space between label and link name)

`sphinx docs`_
        .. _sphinx docs: http://www.sphinx-doc.org

Implicit Links to Title (if title and links are within same rst file):

`Hyperlinks`_

Explicit Links (label is to be defined at the top of documentation):

.. _overview:

Label can be referred in two ways:

overview_ (link appeared as a label name)

:ref:`overview` (link appeared as a Title Name, 'ref' is used to link external RST file)

Example of substitution

Subsequent indented lines comprise the body of the topic, and are interpreted as body elements.

Some text that requires a footnote [1] .

first item
second item

3d item
4th item

5th item
6th item

Whatever:	this is handy to create new field
nocomments:	some contents

Footnotes

[1]	Text of the first footnote.

csv-example¶
Fullname	Address
User A	Lalitpur,
User B	Kathmandu