diff --git a/doc/contributor-guide/source/rst-conv.rst b/doc/contributor-guide/source/rst-conv.rst
index 398ce675ec..e6b9c7a94c 100644
--- a/doc/contributor-guide/source/rst-conv.rst
+++ b/doc/contributor-guide/source/rst-conv.rst
@@ -1,322 +1,52 @@
-
.. _rst_conv:
==========================
RST formatting conventions
==========================
-Follow these guidelines for all the RST source files to keep the documentation
-format consistent.
+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.
-General guidelines
-~~~~~~~~~~~~~~~~~~
-
-Lines length
-------------
-
-Wrap source lines so that lines length does not exceed 79 characters.
-This requirement matches PEP8 standards (from Python) and helps with
-side-by-side diffs on reviews.
+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::
- Exception to this rule is the content of code-block elements and links
- within the references.
+ All the examples provided in this chapter are for illustration purposes
+ only and cannot be regarded as pieces of true technical information.
-When formatting a table that presupposes long lines of text, give
-the preference to one of the following methods over the ``table`` directive:
+.. toctree::
+ :maxdepth: 2
-* format a table using the ``list-table`` directive;
-* format a table using the ``csv-table`` directive;
-* format information as definition lists to avoid tables where possible.
-
-Space and tab characters
-------------------------
-
-* Do not use tab characters within the code; use space characters instead.
-
-* Do not place space characters at the end of lines. If used,
- the checkniceness test will fail because of the trailing whitespaces.
+ 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
-.. _cg_titles:
-
-Titles
-~~~~~~
-
-Each RST source file has the tree structure. Define up to three heading
-levels within one file using the following non-alphanumeric characters:
-
-* **Heading 1** - underline and overline with equal signs;
-
- * **Heading 2** - underline with tildes;
-
- * **Heading 3** - underline with dashes.
-
-**Input**
-
-.. code::
-
- =========
- Heading 1
- =========
-
- Body of the first level section that includes general overview
- of the subject to be covered by the whole section.
- Can include several focused Heading-2-sections.
-
- Heading 2
- ~~~~~~~~~
-
- Body of the second level section that gives detailed explanation of one
- of the aspects of the subject. Can include several Heading-3-sections.
-
- Within user guides, it is mostly used to entitle a procedure with a set
- of actions targeted at a single task performance.
- For example, "Associate floating IP addresses".
-
- Heading 3
- ---------
-
- Body of the third level section.
- It includes very specific content; and occurs mainly in guides containing
- technical information for advanced users.
-
-.. note::
-
- Under- and overlines should be of the same length
- as that of the heading text.
-
- Avoid using lower heading levels by information
- rewriting and reorganizing.
-
-
-Specific information
-~~~~~~~~~~~~~~~~~~~~
-
-Use special markups to emphasize specific content within the text.
-Depending on specific semantic meaning of the message, you can use:
-
-* **note** - for a message of generic meaning.
-
-* **warning** or **important** - includes details that can be easily missed,
- but should not be ignored by a user and are valuable before proceeding.
-
-* **caution** - delivers information that prevents a user from mistakes
- and undesirable consequences when following the procedures.
-
-* **tip** - wraps extra but helpful information.
-
-Here is the example of the note directive usage; these can be applied to all
-the admonition directives described above.
-
-**Input**
-
-.. code::
-
- .. note:: This is the text of a generic admonition.
- This line is the continuation of the first line.
-
- Note may contain bulleted or enumerated lists,
- as well as code blocks:
-
- * first option,
- * ...
-
-**Output**
-
-.. note:: This is the text of a note admonition.
- This line is the continuation of the first line.
-
- Note may contain bulleted or enumerated lists,
- as well as code blocks:
-
- * first option,
- * ...
-
-
-Code samples
+Useful links
~~~~~~~~~~~~
-Format code snippets as standalone literal blocks. There are several ways
-to define a code-block within an RST file.
+* `Sphinx documentation <http://sphinx.readthedocs.org/en/latest/rest.html>`_
-Standard literal block
-----------------------
+* `reStructuredText: Markup Syntax and Parser Component of Docutils
+ <http://docutils.sourceforge.net/rst.html>`_
-+------------------+---------------------------------------------------------+
-| **Directive** | ``::`` or ``code`` |
-+------------------+---------------------------------------------------------+
-| **Arguments** | none |
-+------------------+---------------------------------------------------------+
-| **Options** | none |
-+------------------+---------------------------------------------------------+
-| **Description** | * Introduces a standard reST literal block. |
-| | * Preserves line breaks and whitespaces. |
-| | * Automatically highlights language (Python, by |
-| | default) |
-+------------------+---------------------------------------------------------+
-
-Use ``::`` or ``code`` directive if you provide the code snippets written
-in one programming language within one file. By default, the code-block
-formatted this way is shown in a Python highlighting mode.
-
-To define another highlighting language, specify the ``highlight`` directive
-at the top of the file. Use the ``linenothreshold`` option with it
-to enumerate lines within the code-block.
-
-Always switch on the enumeration for the code-blocks that include more
-than 5 lines.
-
-**Input**
-
-.. code::
-
- .. highlight:: console
- :linenothreshold: 5
-
- This is the file body with the code snippet within:
-
- ::
-
- $ neutron ext-list -c alias -c name
- +-----------------+--------------------------+
- | alias | name |
- +-----------------+--------------------------+
- | agent_scheduler | Agent Schedulers |
- | binding | Port Binding |
- | quotas | Quota management support |
- | ... | ... |
- +-----------------+--------------------------+
-
-
-Non-standard literal block
---------------------------
-
-+------------------+---------------------------------------------------------+
-| **Directive** | ``code-block`` |
-+------------------+---------------------------------------------------------+
-| **Arguments** | ``python`` (default), ``ruby``, ``c``, ``console``, |
-| | ``ini``, and others |
-+------------------+---------------------------------------------------------+
-| **Options** | ``linenos``, ``emphasize-lines`` |
-+------------------+---------------------------------------------------------+
-| **Description** | * Specifies the highlighting language directly. |
-| | * Preserves line breaks and whitespaces. |
-| | * Has special options to number lines and emphasize |
-| | specific lines within the block. |
-+------------------+---------------------------------------------------------+
-
-To optimize the output of code for a specific programming language, specify
-the corresponding argument with ``code-block``. Use ``ini`` for configuration
-files, ``console`` for console inputs and outputs, and so on.
-
-Specify ``linenos`` for automatic enumeration of the code-blocks that include
-more than 5 lines.
-
-If you need to draw a user's attention to the particular code lines, use
-the ``emphasize-lines`` option followed by the numbers of the lines to
-emphasize.
-
-**Input**
-
-.. code::
-
- .. code-block:: ini
- :emphasize-lines: 1, 4
-
- # Configuration for nova-rootwrap
- # This file should be owned by (and only-writeable by) the root user
-
- [DEFAULT]
- # List of directories to load filter definitions from (separated by ',').
-
-
-
-
-References
-~~~~~~~~~~
-
-Cross-references
-----------------
-
-To cross-reference to arbitrary locations within one document,
-use the ``ref`` role:
-
-**Input**
-
-.. code::
-
- .. _cg_titles:
-
- Titles
- ~~~~~~
-
- This is the section we want to reference to.
-
- ...
-
- The following - :ref:`cg_titles` - generates a link to the section with
- the defined label using this section heading as a link title.
-
- A link label and a reference can be defined in separate source files,
- but within one directory. Otherwise, use the external linking.
-
-**Output**
-
-...
-
-The following - :ref:`cg_titles` - generates a link to the section with
-the defined label using this section heading as a link title.
-
-A link label and a reference can be defined in separate source files,
-but within one directory. Otherwise, use the external linking.
-
-
-External references
--------------------
-
-To link to some external locations, format RST source as follows:
-
-#. Do not apply any markups to specify a web link.
-#. If you need a specific link title to appear in the output,
- format a web link as ``Link text <http://web-link.com>``
- wrapping it in backticks.
-#. If a source file contains a big number of external references,
- you can separate a link from its definition for better readability
- while reviewing as shown in the example.
-
-**Input**
-
-.. code::
-
- Here is a link to the User guide: http://docs.openstack.org/user-guide/.
-
- Here is an external web link with a link title:
- `User guide <http://docs.openstack.org/user-guide/>`_.
-
- Here is an external web link separated from its definition:
- This paragraph contains the link to `User guide`_.
-
- ...
-
- .. format the link definition at the end of the file as follows:
- .. _`User guide`: http://docs.openstack.org/user-guide/
-
-
-**Output**
-
-Here is a link to the User guide: http://docs.openstack.org/user-guide/.
-
-Here is an external web link with a link title:
-`User guide <http://docs.openstack.org/user-guide/>`_.
-
-Here is an external web link separated from its definition:
-This paragraph contains the link to `User guide`_.
-
-...
-
-.. format the link definition at the end of the file as follows:
-.. _`User guide`: http://docs.openstack.org/user-guide/
+* `Quick reStructuredText <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
diff --git a/doc/contributor-guide/source/rst-conv/comment.rst b/doc/contributor-guide/source/rst-conv/comment.rst
new file mode 100644
index 0000000000..3d1cf932e9
--- /dev/null
+++ b/doc/contributor-guide/source/rst-conv/comment.rst
@@ -0,0 +1,19 @@
+========
+Comments
+========
+
+Indicate a comment by means of the ``..`` marker.
+
+**Input**
+
+.. code::
+
+ .. This is a comment. It is not visible in the documentation build.
+ Generally, use it to include TODO within the content followed
+ by the initials of the person who is to perform the action.
+
+ For example:
+
+ .. TODO(OG): add a link to the Decorations section when it is available.
+
+
diff --git a/doc/contributor-guide/source/rst-conv/decor.rst b/doc/contributor-guide/source/rst-conv/decor.rst
new file mode 100644
index 0000000000..3a94661177
--- /dev/null
+++ b/doc/contributor-guide/source/rst-conv/decor.rst
@@ -0,0 +1,81 @@
+===========
+Decorations
+===========
+
+Sometimes, the documentation build does not look perfect. To improve
+readability and, therefore, understanding of the content, you can use
+some visual decorations.
+
+This section contains a number of bells and whistles that are neither
+conventions nor even recommendations, but extra features of RST markup
+syntax for general educational purposes.
+
+
+Adding a horizontal line
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can create a horizontal line to visually separate content elements
+by typing four ``-`` (hyphen) in a row adding blank lines before and after.
+
+**Input**
+
+.. code::
+
+ Paragraph 1
+
+ ----
+
+ Paragraph 2
+
+**Output**
+
+Paragraph 1
+
+----
+
+Paragraph 2
+
+
+Starting a new line
+~~~~~~~~~~~~~~~~~~~
+
+Use ``|`` (vertical bar) followed by a single white space to start a new line.
+
+**Input**
+
+.. code::
+
+ | The first line of text.
+ | The second line of text (new line).
+ | ...
+
+**Output**
+
+| The first line of text.
+| The second line of text (new line).
+| ...
+
+Adding extra space between two content elements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use ``|`` (vertical bar) adding blank lines before and after it to add extra
+space between two content elements.
+
+**Input**
+
+.. code::
+
+ Paragraph 1
+
+ |
+
+ Paragraph 2
+
+**Output**
+
+Paragraph 1
+
+|
+
+Paragraph 2
+
diff --git a/doc/contributor-guide/source/rst-conv/figures.rst b/doc/contributor-guide/source/rst-conv/figures.rst
new file mode 100644
index 0000000000..1305ef32b4
--- /dev/null
+++ b/doc/contributor-guide/source/rst-conv/figures.rst
@@ -0,0 +1,26 @@
+=======
+Figures
+=======
+
+Use the ``figure`` directive to include an image, figure, or screenshot into
+the documentation.
+
+**Syntax**
+
+::
+
+ .. figure:: file_name.file_extension
+ :option: option_value
+
+The figure directive supports the following options:
+
+* alt
+* height
+* figwidth
+* scale
+* align
+* target
+* figclass
+
+For descriptions of the options and their possible values, refer to the
+`Docutils documentation <http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure>`_.
diff --git a/doc/contributor-guide/source/rst-conv/gen-guidelines.rst b/doc/contributor-guide/source/rst-conv/gen-guidelines.rst
new file mode 100644
index 0000000000..660177372b
--- /dev/null
+++ b/doc/contributor-guide/source/rst-conv/gen-guidelines.rst
@@ -0,0 +1,49 @@
+==================
+General guidelines
+==================
+
+Lines length
+~~~~~~~~~~~~
+
+Wrap source lines so that lines length does not exceed 79 characters.
+This requirement matches PEP8 standards (from Python) and helps with
+side-by-side diffs on reviews.
+
+.. note::
+
+ Exception to this rule is the content of code-block elements and links
+ within the references.
+
+When formatting a table that presupposes long lines of text, give
+preference to one of the following methods over the ``table`` directive:
+
+* Format a table using the ``list-table`` directive.
+* Format a table using the ``csv-table`` directive.
+* Format information as definition lists to avoid tables where possible.
+
+Space and tab characters
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Do not use tab characters within the code, use space characters instead.
+
+* Do not place space characters at the end of lines. If used,
+ the checkniceness test will fail because of trailing whitespaces.
+
+Indentation
+~~~~~~~~~~~
+
+Use indentation very carefully and keep it consistent since it is significant
+for content nesting. Any indentation that differs from the previous
+one in length, terminates the current level of content either introducing
+a new content sublevel, or shifting to an upper content level.
+
+Use indentation to format the nested content within:
+
+* Definition lists
+* Admonitions (notes, warnings, and so on)
+* Code blocks
+* List and CSV tables
+
+For more information on how to format elements from the list above,
+see the related section of this chapter.
+
diff --git a/doc/contributor-guide/source/rst-conv/inline-markups.rst b/doc/contributor-guide/source/rst-conv/inline-markups.rst
new file mode 100644
index 0000000000..d4f7f68472
--- /dev/null
+++ b/doc/contributor-guide/source/rst-conv/inline-markups.rst
@@ -0,0 +1,202 @@
+===============
+Inline elements
+===============
+
+Sphinx enables specific pieces of inline text. This is emphasized by
+semantic markups that format text in a different style.
+
+Use the markups included in this section as consistent with their semantic
+meaning.
+
+.. note::
+
+ An inline semantic markup has no effect when applied to a piece of text
+ within a code-block element.
+
+To insert a semantic markup into your document, use the syntax below.
+
+**Syntax**
+
+::
+
+ :markup:`inline text`
+
+
+Application
+~~~~~~~~~~~
+
+A software application within a line of text.
+
++------------------------+---------------------------------------------------+
+| **Markup** | ``:program:`` |
++------------------------+---------------------------------------------------+
+| **Syntax** | ``:program:`RabbitMQ``` |
++------------------------+---------------------------------------------------+
+| **Example of output** | Configure :program:`RabbitMQ`. |
++------------------------+---------------------------------------------------+
+
+Code
+~~~~
+
+A fragment of code within a line of text.
+
++------------------------+---------------------------------------------------+
+| **Markup** | `````` (double backticks) |
++------------------------+---------------------------------------------------+
+| **Syntax** | `` ``m1.small`` `` |
++------------------------+---------------------------------------------------+
+| **Example of output** | The following command launches an instance with |
+| | the ``m1.small`` flavor. |
++------------------------+---------------------------------------------------+
+
+Command
+~~~~~~~
+
+An inline sub-command for the command-line interfaces and inline command for
+different operating systems.
+
++------------------------+---------------------------------------------------+
+| **Markup** | ``:command:`` |
++------------------------+---------------------------------------------------+
+| **Syntax** | ``:command:`nova boot``` |
++------------------------+---------------------------------------------------+
+| **Example of output** | Run the :command:`nova boot` command to launch |
+| | an instance. |
++------------------------+---------------------------------------------------+
+
+File name and path
+~~~~~~~~~~~~~~~~~~
+
+Any part of a path specification, including device name, directory, file
+name, and extension.
+
++------------------------+---------------------------------------------------+
+| **Markup** | `````` (double backticks) |
++------------------------+---------------------------------------------------+
+| **Syntax** | ````nova.conf```` |
++------------------------+---------------------------------------------------+
+| **Example of output** | By default, the ``nova.conf`` configuration |
+| | file is installed in the ``/etc/nova`` folder. |
++------------------------+---------------------------------------------------+
+
+Glossary entry
+~~~~~~~~~~~~~~
+
+A term that appears in the glossary.
+
++------------------------+---------------------------------------------------+
+| **Markup** | ``:term:`` |
++------------------------+---------------------------------------------------+
+| **Syntax** | ``:term:`bare``` |
++------------------------+---------------------------------------------------+
+| **Example of output** | |
++------------------------+---------------------------------------------------+
+
+GUI element
+~~~~~~~~~~~
+
+Any part of interactive user interface.
+
++------------------------+---------------------------------------------------+
+| **Markup** | ``:guilabel:`` |
++------------------------+---------------------------------------------------+
+| **Syntax** | ``:guilabel:`Project tab``` |
++------------------------+---------------------------------------------------+
+| **Example of output** | From the :guilabel:`Project tab` you can view and |
+| | manage the resources in a selected project. |
++------------------------+---------------------------------------------------+
+
+Keyboard key combination
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+A sequence of two or more keystrokes or mouse actions.
+
++------------------------+---------------------------------------------------+
+| **Markup** | `````` (double backticks) |
++------------------------+---------------------------------------------------+
+| **Syntax** | ````Ctrl+A```` |
++------------------------+---------------------------------------------------+
+| **Example of output** | Press ``Ctrl+A`` to switch between services. |
++------------------------+---------------------------------------------------+
+
+Menu sequence
+~~~~~~~~~~~~~
+
+An action of navigating a menu to select an item one or more levels down.
+
++------------------------+---------------------------------------------------+
+| **Markup** | ``:menuselection:`` |
++------------------------+---------------------------------------------------+
+| **Syntax** | ``:menuselection:`Project > Compute``` |
++------------------------+---------------------------------------------------+
+| **Example of output** | Go to the :menuselection:`Project > Compute` tab. |
++------------------------+---------------------------------------------------+
+
+Parameter
+~~~~~~~~~
+
+Any parameter for sub-commands for the command-line interfaces.
+
++------------------------+---------------------------------------------------+
+| **Markup** | ``:option:`` to mark parameters that start with |
+| | ``-`` or ``--``, `````` (double backticks) for |
+| | any other parameter |
++------------------------+---------------------------------------------------+
+| **Syntax** | ``:option:`--template-url```, ````back end```` |
++------------------------+---------------------------------------------------+
+| **Example of output** | * You can specify the URL with the |
+| | :option:`--template-url` parameter. |
+| | * Set the ``back end`` parameter. |
++------------------------+---------------------------------------------------+
+
+Option
+~~~~~~
+
+Any option for sub-commands for the command-line interfaces or configuration
+option.
+
++------------------------+---------------------------------------------------+
+| **Markup** | ``:option:`` to mark options that start with |
+| | ``-`` or ``--``, `````` (double backticks) for |
+| | any other parameter |
++------------------------+---------------------------------------------------+
+| **Syntax** | ``:option:`--parent```, |
+| | ````force_dhcp_release = True```` |
++------------------------+---------------------------------------------------+
+| **Example of output** | * The :option:`--parent` stands for the parent of |
+| | the project (name or ID). |
+| | * The ``force_dhcp_release = True`` option sends |
+| | a dhcp release on instance termination. |
++------------------------+---------------------------------------------------+
+
+.. note::
+
+ When documenting Boolean configuration options:
+
+ * Explicitly include the truth value
+ * Add spaces around the equal sign (``=``)
+
+ **Correct usage**
+
+ ::
+
+ force_dhcp_release = True
+ use_ipv6 = False
+
+Variable
+~~~~~~~~
+
+A literal text with a *variable* part in it wrapped in curly braces.
+
++------------------------+---------------------------------------------------+
+| **Markup** | ``:samp:`` to mark variables with curly braces. |
+| | Do not add any additional formatting |
+| | to the replaceable text. |
++------------------------+---------------------------------------------------+
+| **Syntax** | ``:samp:`--flavor {FLAVOR}``` |
++------------------------+---------------------------------------------------+
+| **Example of output** | Use the :samp:`--flavor {FLAVOR}` parameter to |
+| | specify the ID or name of the flavor. |
++------------------------+---------------------------------------------------+
+
+
diff --git a/doc/contributor-guide/source/rst-conv/lists.rst b/doc/contributor-guide/source/rst-conv/lists.rst
new file mode 100644
index 0000000000..bee23d9bbd
--- /dev/null
+++ b/doc/contributor-guide/source/rst-conv/lists.rst
@@ -0,0 +1,130 @@
+=====
+Lists
+=====
+
+Select the appropriate list type to present a sequence of items.
+
+Enumerated lists
+~~~~~~~~~~~~~~~~
+
+Use the enumerated list formatting for a sequence of items whose order
+matters.
+
+**Input**
+
+.. code::
+
+ During the migration process the target host:
+
+ #. Ensures that live migration is enabled.
+ #. Installs the base VHD if it is not already present.
+
+**Output**
+
+During the migration process the target host:
+
+#. Ensures that live migration is enabled.
+#. Installs the base VHD if it is not already present.
+
+Bulleted lists
+~~~~~~~~~~~~~~
+
+Use the bulleted list for a sequence of items that can happen in any order
+or whose order does not matter.
+
+**Input**
+
+.. code::
+
+ Valid formats include:
+
+ * PNG
+ * JPG
+ * GIF
+ * SVG
+
+**Output**
+
+Valid formats include:
+
+* PNG
+* JPG
+* GIF
+* SVG
+
+Definition lists
+~~~~~~~~~~~~~~~~
+
+Use the definition list for an unordered list in which each item has a short
+term. For example, key, option, or phrase, followed by its definition.
+
+Consider using a variable list instead of:
+
+* An itemized list when your list has a regular pattern of key/value or
+ term/definition pairs.
+
+* A two column table where the first column lists items of a consistent type
+ and the second column describes the items.
+
+**Input**
+
+.. code::
+
+ Spellchecking
+ Process of correcting spelling
+
+ Pagebreaking
+ Process of breaking pages
+
+**Output**
+
+Spellchecking
+ Process of correcting spelling
+
+Pagebreaking
+ Process of breaking pages
+
+Mixed lists
+~~~~~~~~~~~
+
+Use the mixed types of lists to nest lists of different types.
+
+**Input**
+
+.. code::
+
+ #. The system exposes these components to users:
+
+ Component A
+ Description of A.
+
+ Component B
+ Description of B.
+
+ Component C
+ Description of C. Note: C is available only for these OS's:
+
+ * Linux
+ * Mac OS X
+
+ #. API libraries are available.
+
+**Output**
+
+#. The system exposes these components to users:
+
+ Component A
+ Description of A.
+
+ Component B
+ Description of B.
+
+ Component C
+ Description of C. Note: C is available only for these OS's:
+
+ * Linux
+ * Mac OS X
+
+#. API libraries are also available.
+
+
diff --git a/doc/contributor-guide/source/rst-conv/profiling.rst b/doc/contributor-guide/source/rst-conv/profiling.rst
new file mode 100644
index 0000000000..872e138361
--- /dev/null
+++ b/doc/contributor-guide/source/rst-conv/profiling.rst
@@ -0,0 +1,55 @@
+===============================
+Profiling (conditional content)
+===============================
+
+Installation Guides has content that depends upon the operating systems.
+
+Use the ``only`` directive to specify the content that is operating-system
+specific. Define one or several tags depending on the operating system
+the content belongs to.
+
+The valid tags for the ``only`` directive are:
+
+* ``ubuntu`` for Ubuntu
+* ``debian`` for Debian
+* ``rdo`` for Red Hat Enterprise Linux, CentOS, and Fedora
+* ``obs`` for openSUSE and SUSE Linux Enterprise
+
+**Input**
+
+.. code::
+
+ Install the NTP service
+ -----------------------
+
+ .. only:: ubuntu or debian
+
+ .. code-block:: console
+
+ # apt-get install chrony
+
+ .. only:: rdo
+
+ .. code-block:: console
+
+ # yum install chrony
+
+ .. only:: obs
+
+ On openSUSE:
+
+ .. code-block:: console
+
+ # zypper addrepo http://download.opensuse.org/repositories/network:time/openSUSE_13.2/network:time.repo
+ ...
+
+ On SLES:
+
+ .. code-block:: console
+
+ # zypper addrepo http://download.opensuse.org/repositories/network:time/SLE_12/network:time.repo
+ ...
+
+For more details refer to `Including content based on tags
+<http://sphinx.readthedocs.org/en/latest/markup/misc.html?highlight=only%20directive#including-content-based-on-tags>`_.
+
diff --git a/doc/contributor-guide/source/rst-conv/refs.rst b/doc/contributor-guide/source/rst-conv/refs.rst
new file mode 100644
index 0000000000..19c60d3e2d
--- /dev/null
+++ b/doc/contributor-guide/source/rst-conv/refs.rst
@@ -0,0 +1,87 @@
+==========
+References
+==========
+
+Cross-references
+~~~~~~~~~~~~~~~~
+
+To cross-reference to arbitrary locations within one document,
+use the ``ref`` role:
+
+**Input**
+
+.. code::
+
+ .. _cg_titles:
+
+ Titles
+ ~~~~~~
+
+ This is the section we want to reference to.
+
+ ...
+
+ The following - :ref:`cg_titles` - generates a link to the section with
+ the defined label using this section heading as a link title.
+
+ A link label and a reference can be defined in separate source files,
+ but within one directory. Otherwise, use the external linking.
+
+**Output**
+
+...
+
+The following - :ref:`cg_titles` - generates a link to the section with
+the defined label using this section heading as a link title.
+
+A link label and a reference can be defined in separate source files,
+but within one directory. Otherwise, use the external linking.
+
+External references
+~~~~~~~~~~~~~~~~~~~
+
+To link to some external locations, format RST source as follows:
+
+* Do not apply any markups to specify a web link.
+
+* If you need a specific link title to appear in the output,
+ format a web link as ``Link text <http://web-link.com>``
+ wrapping it in backticks.
+
+* If a source file contains a big number of external references,
+ you can separate a link from its definition for better readability
+ while reviewing as shown in the example.
+
+**Input**
+
+.. code::
+
+ Here is a link to the User guide: http://docs.openstack.org/user-guide/.
+
+ Here is an external web link with a link title:
+ `User guide <http://docs.openstack.org/user-guide/>`_.
+
+ Here is an external web link separated from its definition:
+ This paragraph contains the link to `User guide`_.
+
+ ...
+
+ .. format the link definition at the end of the file as follows:
+ .. _`User guide`: http://docs.openstack.org/user-guide/
+
+**Output**
+
+Here is a link to the User guide: http://docs.openstack.org/user-guide/.
+
+Here is an external web link with a link title:
+`User guide <http://docs.openstack.org/user-guide/>`_.
+
+Here is an external web link separated from its definition:
+This paragraph contains the link to `User guide`_.
+
+...
+
+.. format the link definition at the end of the file as follows:
+.. _`User guide`: http://docs.openstack.org/user-guide/
+
+
diff --git a/doc/contributor-guide/source/rst-conv/source-code.rst b/doc/contributor-guide/source/rst-conv/source-code.rst
new file mode 100644
index 0000000000..3ab0369ffd
--- /dev/null
+++ b/doc/contributor-guide/source/rst-conv/source-code.rst
@@ -0,0 +1,90 @@
+============
+Code samples
+============
+
+Format code snippets as standalone literal blocks. There are several ways
+to define a code-block within an RST file.
+
+Standard literal block
+~~~~~~~~~~~~~~~~~~~~~~
+
++------------------+---------------------------------------------------------+
+| **Directive** | ``::`` or ``code`` |
++------------------+---------------------------------------------------------+
+| **Arguments** | none |
++------------------+---------------------------------------------------------+
+| **Options** | none |
++------------------+---------------------------------------------------------+
+| **Description** | * Introduces a standard reST literal block. |
+| | * Preserves line breaks and whitespaces. |
+| | * Automatically highlights language (Python, by |
+| | default) |
++------------------+---------------------------------------------------------+
+
+Use ``::`` or ``code`` directive if you provide the code snippets written
+in one programming language within one file. By default, the code-block
+formatted this way is shown in a Python highlighting mode.
+
+To define another highlighting language, use the ``code-block`` directive
+as described in the :ref:`non-standard-block` section.
+
+**Input**
+
+.. code::
+
+ Add logging statements::
+
+ from nova.openstack.common import log as logging
+ LOG = logging.getLogger(__name__)
+
+**Output**
+
+Add logging statements::
+
+ from nova.openstack.common import log as logging
+ LOG = logging.getLogger(__name__)
+
+
+.. _non-standard-block:
+
+Non-standard literal block
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
++------------------+---------------------------------------------------------+
+| **Directive** | ``code-block`` |
++------------------+---------------------------------------------------------+
+| **Arguments** | ``python`` (default), ``ruby``, ``c``, ``console``, |
+| | ``ini``, and others |
++------------------+---------------------------------------------------------+
+| **Options** | ``linenos``, ``emphasize-lines`` |
++------------------+---------------------------------------------------------+
+| **Description** | * Specifies the highlighting language directly. |
+| | * Preserves line breaks and whitespaces. |
++------------------+---------------------------------------------------------+
+
+To optimize the output of code for a specific programming language, specify
+the corresponding argument with ``code-block``. Use ``ini`` for configuration
+files, ``console`` for console inputs and outputs, and so on.
+
+**Input**
+
+.. code::
+
+ .. code-block:: ini
+
+ # Configuration for nova-rootwrap
+ # This file should be owned by (and only-writeable by) the root user
+
+ [DEFAULT]
+ # List of directories to load filter definitions from (separated by ',').
+
+**Output**
+
+.. code-block:: ini
+
+ # Configuration for nova-rootwrap
+ # This file should be owned by (and only-writeable by) the root user
+
+ [DEFAULT]
+ # List of directories to load filter definitions from (separated by ',').
+
diff --git a/doc/contributor-guide/source/rst-conv/spec-info.rst b/doc/contributor-guide/source/rst-conv/spec-info.rst
new file mode 100644
index 0000000000..830b630ebc
--- /dev/null
+++ b/doc/contributor-guide/source/rst-conv/spec-info.rst
@@ -0,0 +1,48 @@
+===========================
+Specific information blocks
+===========================
+
+Use special markups to emphasize specific information within your document.
+Depending on specific semantic meaning of the message, you can use:
+
+* **note** - for a message of generic meaning.
+
+* **warning** or **important** - includes details that can be easily missed,
+ but should not be ignored by a user and are valuable before proceeding.
+
+* **caution** - delivers information that prevents a user from mistakes
+ and undesirable consequences when following the procedures.
+
+* **tip** - wraps extra but helpful information.
+
+Here is the example of the note directive usage; these can be applied to all
+the admonition directives described above.
+
+**Input**
+
+.. code::
+
+ .. note::
+
+ This is the text of a generic admonition.
+ This line is the continuation of the first line.
+
+ A note may contain bulleted or enumerated lists,
+ as well as code blocks:
+
+ * first option,
+ * ...
+
+**Output**
+
+.. note::
+
+ This is the text of a note admonition.
+ This line is the continuation of the first line.
+
+ Note may contain bulleted or enumerated lists,
+ as well as code blocks:
+
+ * first option,
+ * ...
+
diff --git a/doc/contributor-guide/source/rst-conv/tables.rst b/doc/contributor-guide/source/rst-conv/tables.rst
new file mode 100644
index 0000000000..d077de21ab
--- /dev/null
+++ b/doc/contributor-guide/source/rst-conv/tables.rst
@@ -0,0 +1,127 @@
+======
+Tables
+======
+
+Graphic tables
+~~~~~~~~~~~~~~
+
+Use the graphic table formatting for the content that presupposes short
+lines of text and a small number of rows and columns.
+
+.. note::
+
+ As the graphic tables are rather difficult to create and maintain,
+ give the preference to list and CSV tables over the graphic ones,
+ or format the content as definition lists where possible.
+
+**Input**
+
+.. code::
+
+ ============ ========= =============== =============
+ Flavor VCPUs Disk (in GB) RAM (in MB)
+ ============ ========= =============== =============
+ m1.tiny 1 1 512
+ m1.small 1 20 2048
+ m1.medium 2 40 4096
+ m1.large 4 80 8192
+ m1.xlarge 8 160 16384
+ ============ ========= =============== =============
+
+**Output**
+
+============ ========= =============== =============
+ Flavor VCPUs Disk (in GB) RAM (in MB)
+============ ========= =============== =============
+ m1.tiny 1 1 1
+ m1.small 1 20 2048
+ m1.medium 2 40 4096
+ m1.large 4 80 8192
+ m1.xlarge 8 160 16384
+============ ========= =============== =============
+
+List tables
+~~~~~~~~~~~
+
+Use the ``list-table`` directive to create a table that contains a large
+number of raws and columns with the long lines within the cells.
+
+**Input**
+
+.. code::
+
+ .. list-table:: **Quota descriptions**
+ :widths: 10 25 10
+ :header-rows: 1
+
+ * - Quota Name
+ - Defines the number of
+ - Service
+ * - Gigabytes
+ - Volume gigabytes allowed for each project
+ - Block Storage
+ * - Instances
+ - Instances allowed for each project.
+ - Compute
+ * - Injected File Content Bytes
+ - Content bytes allowed for each injected file.
+ - Compute
+
+**Output**
+
+.. list-table:: **Quota descriptions**
+ :widths: 10 25 10
+ :header-rows: 1
+
+ * - Quota Name
+ - Defines the number of
+ - Service
+ * - Gigabytes
+ - Volume gigabytes allowed for each project
+ - Block Storage
+ * - Instances
+ - Instances allowed for each project.
+ - Compute
+ * - Injected File Content Bytes
+ - Content bytes allowed for each injected file.
+ - Compute
+
+CSV tables
+~~~~~~~~~~
+
+The ``csv-table`` directive enables creating a table from CSV
+(comma-separated values) data. It also supports RST inline markups,
+such as, emphasis, strong emphasis markups, code, command, and other
+directives.
+
+**Input**
+
+.. code::
+
+ .. csv-table:: **ipv6_ra_mode and ipv6_address_mode combinations**
+ :header: ipv6 ra mode, ipv6 address mode, "radvd A,M,O", "External Router A,M,O", Description
+ :widths: 2, 2, 2, 2, 4
+
+ *N/S*, *N/S*, Off, Not Defined, Backwards compatibility with pre-Juno IPv6 behavior.
+ *N/S*, slaac, Off, "1,0,0", Guest instance obtains IPv6 address from non-OpenStack
+ *N/S*, dhcpv6-stateful, Off, "0,1,1", Not currently implemented in the reference implementation.
+
+**Output**
+
+.. csv-table:: **ipv6_ra_mode and ipv6_address_mode combinations**
+ :header: ipv6 ra mode, ipv6 address mode, "radvd A,M,O", "External Router A,M,O", Description
+ :widths: 2, 2, 2, 2, 4
+
+ *N/S*, *N/S*, Off, Not Defined, Backwards compatibility with pre-Juno IPv6 behavior.
+ *N/S*, slaac, Off, "1,0,0", Guest instance obtains IPv6 address from non-OpenStack
+ *N/S*, dhcpv6-stateful, Off, "0,1,1", Not currently implemented in the reference implementation.
+
+
+Useful links on table formatting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* `Graphic tables formatting details <http://docutils.sourceforge.net/docs/user/rst/quickref.html#tables>`_
+
+* `List tables formatting details <http://docutils.sourceforge.net/docs/ref/rst/directives.html#list-table>`_
+
+* `CSV tables formatting details <http://docutils.sourceforge.net/docs/ref/rst/directives.html#id48>`_
diff --git a/doc/contributor-guide/source/rst-conv/titles.rst b/doc/contributor-guide/source/rst-conv/titles.rst
new file mode 100644
index 0000000000..46eeb8f485
--- /dev/null
+++ b/doc/contributor-guide/source/rst-conv/titles.rst
@@ -0,0 +1,52 @@
+.. _cg_titles:
+
+======
+Titles
+======
+
+Each RST source file has the tree structure. Define up to three heading
+levels within one file using the following non-alphanumeric characters:
+
+* **Heading 1** - underline and overline with equal signs;
+
+ * **Heading 2** - underline with tildes;
+
+ * **Heading 3** - underline with dashes.
+
+**Input**
+
+.. code::
+
+ =========
+ Heading 1
+ =========
+
+ Body of the first level section that includes general overview
+ of the subject to be covered by the whole section.
+ Can include several focused Heading-2-sections.
+
+ Heading 2
+ ~~~~~~~~~
+
+ Body of the second level section that gives detailed explanation of one
+ of the aspects of the subject. Can include several Heading-3-sections.
+
+ Within user guides, it is mostly used to entitle a procedure with a set
+ of actions targeted at a single task performance.
+ For example, "Associate floating IP addresses".
+
+ Heading 3
+ ---------
+
+ Body of the third level section.
+ It includes very specific content, and occurs mainly in guides containing
+ technical information for advanced users.
+
+.. note::
+
+ Under- and overlines should be of the same length
+ as that of the heading text.
+
+ Avoid using lower heading levels by information
+ rewriting and reorganizing.
+