c10da1ec38
1. Adds the following subsections: * Introduction to RST * Tables * Images * Profiling * Lists * Inline markups * Decorations * Commenting 2. Restructures the toc 3. Creates separate files for each subsection included in the RST-related folder for simpler maintenance. Change-Id: I08568fb37755109552edf9692b8f259660550a69
53 lines
1.5 KiB
ReStructuredText
53 lines
1.5 KiB
ReStructuredText
.. _rst_conv:
|
|
|
|
==========================
|
|
RST formatting 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
|
|
good-looking documentation creation. It uses simple and implicit
|
|
syntax to introduce a wide range 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/gen-guidelines.rst
|
|
rst-conv/titles.rst
|
|
rst-conv/inline-markups.rst
|
|
rst-conv/lists.rst
|
|
rst-conv/spec-info.rst
|
|
rst-conv/source-code.rst
|
|
rst-conv/refs.rst
|
|
rst-conv/tables.rst
|
|
rst-conv/figures.rst
|
|
rst-conv/profiling.rst
|
|
rst-conv/comment.rst
|
|
rst-conv/decor.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>`_
|
|
|