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
This commit is contained in:
parent
b66db7f99b
commit
31416cf33e
@ -37,6 +37,7 @@ use simpler formatting.
|
|||||||
rst-conv/tables.rst
|
rst-conv/tables.rst
|
||||||
rst-conv/figures.rst
|
rst-conv/figures.rst
|
||||||
rst-conv/profiling.rst
|
rst-conv/profiling.rst
|
||||||
|
rst-conv/rst2bash.rst
|
||||||
rst-conv/comment.rst
|
rst-conv/comment.rst
|
||||||
rst-conv/decorations.rst
|
rst-conv/decorations.rst
|
||||||
|
|
||||||
|
@ -7,7 +7,7 @@ systems.
|
|||||||
|
|
||||||
Use the ``only`` directive to specify the content that is operating-system
|
Use the ``only`` directive to specify the content that is operating-system
|
||||||
specific. Define one or several tags depending on the 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:
|
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
|
* ``rdo`` for Red Hat Enterprise Linux and CentOS
|
||||||
* ``obs`` for openSUSE and SUSE Linux Enterprise
|
* ``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**
|
**Input**
|
||||||
|
|
||||||
.. code-block:: none
|
.. code-block:: none
|
||||||
@ -29,12 +35,20 @@ The valid tags for the ``only`` directive are:
|
|||||||
|
|
||||||
# apt-get install chrony
|
# apt-get install chrony
|
||||||
|
|
||||||
|
.. end
|
||||||
|
|
||||||
|
.. endonly
|
||||||
|
|
||||||
.. only:: rdo
|
.. only:: rdo
|
||||||
|
|
||||||
.. code-block:: console
|
.. code-block:: console
|
||||||
|
|
||||||
# yum install chrony
|
# yum install chrony
|
||||||
|
|
||||||
|
.. end
|
||||||
|
|
||||||
|
.. endonly
|
||||||
|
|
||||||
.. only:: obs
|
.. only:: obs
|
||||||
|
|
||||||
On openSUSE:
|
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
|
# zypper addrepo http://download.opensuse.org/repositories/network:time/openSUSE_13.2/network:time.repo
|
||||||
...
|
...
|
||||||
|
|
||||||
|
.. end
|
||||||
|
|
||||||
On SLES:
|
On SLES:
|
||||||
|
|
||||||
.. code-block:: console
|
.. 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
|
# 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
|
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>`_.
|
<http://sphinx.readthedocs.org/en/latest/markup/misc.html?highlight=only%20directive#including-content-based-on-tags>`_.
|
||||||
|
79
doc/contributor-guide/source/rst-conv/rst2bash.rst
Normal file
79
doc/contributor-guide/source/rst-conv/rst2bash.rst
Normal file
@ -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
|
@ -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.
|
formatted this way is shown in a Python highlighting mode.
|
||||||
|
|
||||||
To define another highlighting language, use the ``code-block`` directive
|
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**
|
**Input**
|
||||||
|
|
||||||
@ -71,6 +81,7 @@ files, ``console`` for console inputs and outputs, and so on.
|
|||||||
|
|
||||||
.. code-block:: none
|
.. code-block:: none
|
||||||
|
|
||||||
|
.. path /path/to/config/file
|
||||||
.. code-block:: ini
|
.. code-block:: ini
|
||||||
|
|
||||||
# Configuration for nova-rootwrap
|
# Configuration for nova-rootwrap
|
||||||
@ -79,6 +90,8 @@ files, ``console`` for console inputs and outputs, and so on.
|
|||||||
[DEFAULT]
|
[DEFAULT]
|
||||||
# List of directories to load filter definitions from (separated by ',').
|
# List of directories to load filter definitions from (separated by ',').
|
||||||
|
|
||||||
|
.. end
|
||||||
|
|
||||||
**Output**
|
**Output**
|
||||||
|
|
||||||
.. code-block:: ini
|
.. code-block:: ini
|
||||||
@ -122,10 +135,13 @@ content from a remote URL (``http`` or ``https``).
|
|||||||
|
|
||||||
.. code-block:: none
|
.. code-block:: none
|
||||||
|
|
||||||
|
.. path /path/to/config/file
|
||||||
.. remote-code-block:: ini
|
.. remote-code-block:: ini
|
||||||
|
|
||||||
http://git.openstack.org/cgit/openstack/nova/tree/etc/nova/api-paste.ini?h=stable/newton
|
http://git.openstack.org/cgit/openstack/nova/tree/etc/nova/api-paste.ini?h=stable/newton
|
||||||
|
|
||||||
|
.. end
|
||||||
|
|
||||||
**Output**
|
**Output**
|
||||||
|
|
||||||
.. code-block:: ini
|
.. code-block:: ini
|
||||||
@ -139,3 +155,4 @@ content from a remote URL (``http`` or ``https``).
|
|||||||
|
|
||||||
[pipeline:meta]
|
[pipeline:meta]
|
||||||
pipeline = cors ec2faultwrap logrequest metaapp
|
pipeline = cors ec2faultwrap logrequest metaapp
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user