88a104d852
Change-Id: Iaefc26222d42663423f736946dea97c5613b7d1c Signed-off-by: Doug Hellmann <doug@doughellmann.com>
49 lines
1.9 KiB
ReStructuredText
49 lines
1.9 KiB
ReStructuredText
====================================
|
|
Sphinx Oslo Sample Policy Generation
|
|
====================================
|
|
|
|
.. note::
|
|
This extension relies on ``oslopolicy-sample-generator``, which requires
|
|
configuration of policies in code to function. Refer to the :doc:`usage`
|
|
guide for more information.
|
|
|
|
oslo.policy includes a sphinx extension to generate a sample policy file at the
|
|
beginning of each sphinx build. This sample policy file can then be included in
|
|
your documents as a raw file, for example, via the ``literalinclude`` directive.
|
|
|
|
To activate the extension add ``oslo_policy.sphinxpolicygen`` to the list of
|
|
extensions in your sphinx ``conf.py``. Once enabled, you need to define two
|
|
options: ``policy_generator_config_file`` and ``sample_policy_basename``. For
|
|
example::
|
|
|
|
policy_generator_config_file = '../../etc/nova/nova-policy-generator.conf'
|
|
sample_policy_basename = '_static/nova'
|
|
|
|
where:
|
|
|
|
``policy_generator_config_file``
|
|
Path to an configuration file used with the ``oslopolicy-sample-generator``
|
|
utility. This can be an full path or a value relative to the documentation
|
|
source directory (``app.srcdir``). If this option is not specified or is
|
|
invalid then the sample policy file generation will be skipped.
|
|
|
|
``sample_policy_basename``
|
|
Base name of the output file. This name will be appended with a
|
|
``.policy.yaml.sample`` extension to generate the final output file and the
|
|
path is relative to documentation source directory (``app.srcdir``). As such,
|
|
using the above example, the policy file will be output to
|
|
``_static/nova.policy.yaml.sample``. If this option is not specified, the
|
|
file will be output to ``sample.policy.yaml``.
|
|
|
|
Once configured, you can include this configuration file in your source:
|
|
|
|
.. code:: reST
|
|
|
|
=============
|
|
Sample Policy
|
|
=============
|
|
|
|
Here is a sample policy file.
|
|
|
|
.. literalinclude:: _static/nova.policy.yaml.sample
|