.. _rst_conv:

===============
RST conventions
===============

OpenStack documentation uses reStructuredText (RST) markup syntax
with Sphinx extensions.

RST is a powerful and straightforward markup language that, in combination
with Sphinx, provides a wide range of facilities for intelligent and
appealing documentation creation. It uses simple and implicit
syntax to introduce a variety of content elements such as titles,
code blocks, vertical lists, and many others. All the source content formatted
using RST is stored in files with the ``.rst`` extension.

To keep the documentation format consistent, follow the guidelines
included in this chapter for all the RST source content. When in doubt,
use simpler formatting.

.. note::

   All the examples provided in this chapter are for illustration purposes
   only and cannot be regarded as pieces of true technical information.

.. toctree::
   :maxdepth: 2

   rst-conv/general-guidelines.rst
   rst-conv/file-naming.rst
   rst-conv/titles.rst
   rst-conv/inline-markups.rst
   rst-conv/lists.rst
   rst-conv/specific-info.rst
   rst-conv/source-code.rst
   rst-conv/references.rst
   rst-conv/tables.rst
   rst-conv/figures.rst
   rst-conv/profiling.rst
   rst-conv/rst2bash.rst
   rst-conv/comment.rst
   rst-conv/decorations.rst

Useful links
~~~~~~~~~~~~

* `Sphinx documentation <http://sphinx.readthedocs.org/en/latest/rest.html>`_
* `reStructuredText: Markup Syntax and Parser Component of Docutils
  <http://docutils.sourceforge.net/rst.html>`_
* `Quick reStructuredText <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_