Document new rst syntax for parser.

Updates rst syntax changes for the installation guides in specific but
could potentially also be followed by other guides providing BASH like
code.

- Documents parser related syntax changes.
- Updates current documentation for profiling (only blocks) and source
  code (code-blocks).

Change-Id: I831b79f01ea9b5c8fe9f7861887d2c14a9e213bc

doc/contributor-guide/source/rst-conv.rst

@@ -37,6 +37,7 @@ use simpler formatting.
    rst-conv/tables.rst
    rst-conv/figures.rst
    rst-conv/profiling.rst
+   rst-conv/rst2bash.rst
    rst-conv/comment.rst
    rst-conv/decorations.rst
 

doc/contributor-guide/source/rst-conv/profiling.rst

@@ -7,7 +7,7 @@ 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 content belongs to. Make sure to close the ``only`` tag with ``endonly``.
 
 The valid tags for the ``only`` directive are:
 
@@ -16,6 +16,12 @@ The valid tags for the ``only`` directive are:
 * ``rdo`` for Red Hat Enterprise Linux and CentOS
 * ``obs`` for openSUSE and SUSE Linux Enterprise
 
+.. note::
+
+  The ``endonly`` tag allows the parser to identify the distro-specific blocks.
+  For more information, refer to the :doc:`rst2bash` section. These
+  changes are mandatory only for the installation guides.
+
 **Input**
 
 .. code-block:: none
@@ -29,12 +35,20 @@ The valid tags for the ``only`` directive are:
 
          # apt-get install chrony
 
+      .. end
+
+   .. endonly
+
    .. only:: rdo
 
       .. code-block:: console
 
          # yum install chrony
 
+      .. end
+
+   .. endonly
+
    .. only:: obs
 
       On openSUSE:
@@ -44,6 +58,8 @@ The valid tags for the ``only`` directive are:
          # zypper addrepo http://download.opensuse.org/repositories/network:time/openSUSE_13.2/network:time.repo
          ...
 
+      .. end
+
       On SLES:
 
       .. code-block:: console
@@ -51,5 +67,9 @@ The valid tags for the ``only`` directive are:
          # zypper addrepo http://download.opensuse.org/repositories/network:time/SLE_12/network:time.repo
          ...
 
+      .. end
+
+   .. endonly
+
 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>`_.

doc/contributor-guide/source/rst-conv/rst2bash.rst

@@ -0,0 +1,79 @@
+=============
+Parser syntax
+=============
+
+Installation guide is parsed directly into Bash code which will be using
+training labs to deploy OpenStack cluster. This should allow us to have
+higher agility for developing installation guides and to automatically
+test changes to the guides.
+
+There are many factors that could lead to execution errors on the install
+guides, but one of the main potential sources of errors relies on the
+limitations of the human eye. The problem becomes specially important
+with the addition of project-specific installation guides.
+
+Additionally, the parser is also enabled with linting capabilities which
+should provide some sort of syntax niceness and validate if the document
+is having the correct syntax for the scope of the parser to successfully
+parse RST to Bash.
+
+To help the parser to validate the document, consider the following
+syntax format.
+
+* The ``code-block`` tags should be closed with ``end``.
+
+  .. code-block:: ini
+
+      .. code-block:: console
+
+          $ echo "Hello, World!"
+
+      .. end
+
+  .. end
+
+* The ``code-block`` tags which rely on path should have ``path``
+  tag one line above without a line break as shown below. May it
+  be some code which has to be run from a specific folder or a
+  configuration file, the parser should know about the path.
+
+  * Example 1: Run a specific command from a given folder.
+
+    .. code-block:: ini
+
+      .. path /usr/local/
+      .. code-block:: console
+
+        $ echo "Run a command from a specific folder"
+        $ chmod -R +rx bin
+
+      .. end
+
+    .. end
+
+  * Example 2: Configure a configuration file.
+
+    .. code-block:: ini
+
+      .. path /etc/keystone/keystone.conf
+      .. code-block:: ini
+
+        [DEFAULT]
+        ...
+        debug = True
+
+      .. end
+
+    .. end
+
+* The ``only`` tags should be closed with ``endonly``.
+
+  .. code-block:: ini
+
+    .. only:: ubuntu or debian
+
+        All related content.
+
+    .. endonly
+
+  .. end

doc/contributor-guide/source/rst-conv/source-code.rst

@@ -28,7 +28,17 @@ 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.
+as described in the :ref:`non-standard-block` section. Make sure to close these
+tags with ``end``. Additionally, add the ``path`` tag to provide the parser
+with the path of the configuration files. This should allow the parser to parse
+the markup syntax to Bash.
+
+.. note::
+
+  The ``end`` tag allows the parser to identify the scope of code blocks.
+  The ``path`` tag allows the parser to identify the path of the config
+  file. For more information, refer to the :doc:`rst2bash` section.
+  These changes are mandatory only for the installation guides.
 
 **Input**
 
@@ -71,6 +81,7 @@ files, ``console`` for console inputs and outputs, and so on.
 
 .. code-block:: none
 
+   .. path /path/to/config/file
    .. code-block:: ini
 
       # Configuration for nova-rootwrap
@@ -79,6 +90,8 @@ files, ``console`` for console inputs and outputs, and so on.
       [DEFAULT]
       # List of directories to load filter definitions from (separated by ',').
 
+   .. end
+
 **Output**
 
 .. code-block:: ini
@@ -122,10 +135,13 @@ content from a remote URL (``http`` or ``https``).
 
 .. code-block:: none
 
+   .. path /path/to/config/file
    .. remote-code-block:: ini
 
       http://git.openstack.org/cgit/openstack/nova/tree/etc/nova/api-paste.ini?h=stable/newton
 
+   .. end
+
 **Output**
 
 .. code-block:: ini
@@ -139,3 +155,4 @@ content from a remote URL (``http`` or ``https``).
 
    [pipeline:meta]
    pipeline = cors ec2faultwrap logrequest metaapp
+