The new sphinx version introduces some changes that break build: * Warns if code cannot be parsed for highlighting. Fix the code so that it can be parsed, this includes uncommenting "..." lines. Note that not every config file is an ini-file. Also, the parser seems to have bugs and cannot parse all files. Fix mysql ini file and enable the parameter, see http://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_file_per_table * :option: works only with declared options, replace useage with simple ``. This change only handles a few files, more to come later. Change-Id: I7c7335e514581622dd562ee355f62d6ae1beaa18
1.9 KiB
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 withend
... code-block:: console $ echo "Hello, World!" .. end
The
code-block
tags which rely on path should havepath
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.
.. path /usr/local/ .. code-block:: console $ echo "Run a command from a specific folder" $ chmod -R +rx bin .. end
Example 2: Configure a configuration file.
.. path /etc/keystone/keystone.conf .. code-block:: ini [DEFAULT] ... debug = True .. end
The
only
tags should be closed withendonly
... only:: ubuntu or debian All related content. .. endonly