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