Using reStructuredText

After using sphinx-quickstart you have the index.rst file which contains the content:

=====================
Quick Sphinx Tutorial
=====================

.. image:: https://travis-ci.org/cehbrecht/quick-sphinx-tutorial.svg?branch=master
   :target: https://travis-ci.org/cehbrecht/quick-sphinx-tutorial
   :alt: Travis Build

Welcome to this short `Sphinx`_ tutorial. This tutorial is a concise
summary of other Sphinx tutorials and will give you a quick overview
of what Sphinx can do for you. If you want to know about the Sphinx
details then have a look at :ref:`appendix` and at `one`_ or the
`other`_ tutorial. 

.. note:: Of course a tutorial about Sphinx is written in `Sphinx`_. You
          can clone this tutorial from `GitHub`_ and it is hosted
          on `ReadTheDocs`_.

.. toctree::
   :maxdepth: 1

   intro
   install
   firststeps
   rst
   code
   rtd
   advanced
   appendix

.. _GitHub: https://github.com/cehbrecht/quick-sphinx-tutorial
.. _one: http://gisellezeno.com/tutorials/sphinx-for-python-documentation.html
.. _other: https://sphinx-tutorial.readthedocs.org/
.. _ReadTheDocs: http://quick-sphinx-tutorial.readthedocs.org/en/latest/

You can create other files here for additional documentation. Once you have created them, then you can include them in the table of contents in index.rst.

Play with reStructuredText (reST) Syntax

reStructuredText takes a bit of practice. Go over to http://rst.ninjs.org, which is a live preview.

To get started with the reST syntax, you can read the reStructuredText Primer in the Sphinx docs.

Warning

reST is extended by Sphinx Markup Constructs to manage metadata, indexing, and cross-references.

Note

The cheatsheet gives an overview of reST and the Sphinx markup extensions.

Quick reST example

An example for reStructuredText:

====================
ReST Quick Reference
====================

Underline titles with punctuation
=================================

.. _rst_example:

ReST example markup
-------------------

*Italic* **bold** ``name`` ``function()`` ``expression = 3 + 3``
`Hyperlink <http://en.wikipedia.org/wiki/Hyperlink>`_ `Link`_

.. _Link: http://en.wikipedia.org/wiki/Link_(The_Legend_of_Zelda)
.. image:: images/python-logo.png
.. A comment block starts with two periods, can continue indented.

A paragraph is one or more lines of un-indented text, separated
from the material above and below by blank lines.

     “Block quotes look like paragraphs, but are indented with
     one or more spaces.”

| Because of the pipe characters, this will become one line,
| And this will become another line, like in poetry.

term
   Definition for the “term”, indented beneath it.
another term
   And its definition; any of these definitions can continue on for
   several lines by — you guessed it! — being similarly indented.

* Each item in a list starts with an asterisk (or “1.”, “a.”, etc).
* List items can go on for several lines as long as you remember to
   keep the rest of the list item indented.

Code blocks are introduced by a double-colon and are indented::

     $ mkdir docs

Examples using Sphinx markup
----------------------------

A python code block using Sphinx markup:

.. code-block:: python

     import docutils
     print help(docutils)

.. note:: This is a note using Sphinx markup.

This is a reference to :ref:`rst_example`.

Note

Life Preview: ReST Quick Reference