| 1 |
==================================== |
| 2 |
Sphinx Oslo Sample Policy Generation |
| 3 |
==================================== |
| 4 |
|
| 5 |
.. note:: |
| 6 |
This extension relies on ``oslopolicy-sample-generator``, which requires |
| 7 |
configuration of policies in code to function. Refer to the :doc:`usage` |
| 8 |
guide for more information. |
| 9 |
|
| 10 |
oslo.policy includes a sphinx extension to generate a sample policy file at the |
| 11 |
beginning of each sphinx build. This sample policy file can then be included in |
| 12 |
your documents as a raw file, for example, via the ``literalinclude`` directive. |
| 13 |
|
| 14 |
To activate the extension add ``oslo_policy.sphinxpolicygen`` to the list of |
| 15 |
extensions in your sphinx ``conf.py``. Once enabled, you need to define two |
| 16 |
options: ``policy_generator_config_file`` and ``sample_policy_basename``. For |
| 17 |
example:: |
| 18 |
|
| 19 |
policy_generator_config_file = '../../etc/nova/nova-policy-generator.conf' |
| 20 |
sample_policy_basename = '_static/nova' |
| 21 |
|
| 22 |
where: |
| 23 |
|
| 24 |
``policy_generator_config_file`` |
| 25 |
Path to an configuration file used with the ``oslopolicy-sample-generator`` |
| 26 |
utility. This can be a full path or a value relative to the documentation |
| 27 |
source directory (``app.srcdir``). If this option is not specified or is |
| 28 |
invalid then the sample policy file generation will be skipped. |
| 29 |
|
| 30 |
To handle cases where multiple files need to be generated, this |
| 31 |
value can be a list of two-part tuples containing the path to the |
| 32 |
configuration file and the base name for the output file (in this |
| 33 |
case, ``sample_policy_basename`` should not be set). |
| 34 |
|
| 35 |
``sample_policy_basename`` |
| 36 |
Base name of the output file. This name will be appended with a |
| 37 |
``.policy.yaml.sample`` extension to generate the final output file, and the |
| 38 |
path is relative to the documentation source directory (``app.srcdir``). As such, |
| 39 |
using the above example, the policy file will be output to |
| 40 |
``_static/nova.policy.yaml.sample``. If this option is not specified, the |
| 41 |
file will be output to ``sample.policy.yaml``. |
| 42 |
|
| 43 |
``exclude_deprecated`` |
| 44 |
Boolean value, default False, controls if the output should include deprecated |
| 45 |
policy information or values, as these can be confusing and misleading |
| 46 |
in some cases. |
| 47 |
|
| 48 |
Once configured, you can include this configuration file in your source: |
| 49 |
|
| 50 |
.. code:: reST |
| 51 |
|
| 52 |
============= |
| 53 |
Sample Policy |
| 54 |
============= |
| 55 |
|
| 56 |
Here is a sample policy file. |
| 57 |
|
| 58 |
.. literalinclude:: _static/nova.policy.yaml.sample |