reStructuredText¶
There are a lot of guides on how reStructuredText works, and this is not a substitute for them. It is just a brief sample of common formatting options that work with Read the Docs for those in a hurry.
reStructuredText Conventions¶
Here are some basic pointers on how to create documentation pages in reStructuredText.
Line length¶
The length of a line in reStructuredText shouldn’t be more than 79 characters
Headings¶
Headings are:
H1¶
A row of #’s above and below the line of text. There should only one H1 in the document. Example:
###############
Heading Level 1
###############
H2¶
A row of *’s above and below the line of text. Example:
***************
Heading Level 2
***************
Text Formatting¶
Lists¶
Lists must always be preceded by a blank line.
Numbered Lists¶
Numbered lists are numbers or letters followed by ”.”, right bracket ”)” or surrounded by brackets “( )”
This is a numbered list:
1) Item 1
2) Item 2
Displays as:
This is a numbered list:
- Item 1
- Item 2
Bullet Points¶
Bullet point lines start with “-”, “+” or “*”
This is a bullet point list:
* Item 1
* Item 2
Displays as:
This is a bullet point list:
- Item 1
- Item 2
Code Blocks¶
Use the code-block directive to display code as it appears, including syntax highlighting if desired.
Command Line¶
Use this directive for text such as command line input and output (note 2 space indent for the code):
.. code-block:: text
code here...
Python¶
Use this directive for Python (note 2 space indent for the code):
.. code-block:: python
code here...
Hyperlinks¶
Simple link¶
(note the backticks, angle brackets and trailing underscore)
`<http://www.python.org/>`_
Link with name¶
`Python <http://www.python.org/>`_
Link to local page¶
`Local Page <local_page.html>`_
Images¶
.. image:: images/build1.png