diff options
author | Stephen Finucane <sfinucan@redhat.com> | 2016-09-26 15:01:28 +0100 |
---|---|---|
committer | Stephen Finucane <sfinucan@redhat.com> | 2016-09-28 10:59:14 +0100 |
commit | fb1e9879e6df063b0a01ed0a56637d432ded9f1f (patch) | |
tree | f4eb5d0ef7253d0dba55962a05559031928f95c4 /doc | |
parent | c4ea3f0c11a9d763efaa5dfe11eb334ff4ffc46f (diff) | |
download | oslo-policy-fb1e9879e6df063b0a01ed0a56637d432ded9f1f.tar.gz |
Add sphinx extension to build sample policy
Provide a way to include a sample policy file in a project's
documentation. This harnesses the same generator utilities used in
standard policy file generation.
Change-Id: I4b04044c18ea9f2b1d55785686982af9032a8495
Diffstat (limited to 'doc')
-rw-r--r-- | doc/source/index.rst | 1 | ||||
-rw-r--r-- | doc/source/sphinxpolicygen.rst | 48 |
2 files changed, 49 insertions, 0 deletions
diff --git a/doc/source/index.rst b/doc/source/index.rst index 8357bac..a433814 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -14,6 +14,7 @@ Contents opts cli contributing + sphinxpolicygen history Indices and tables diff --git a/doc/source/sphinxpolicygen.rst b/doc/source/sphinxpolicygen.rst new file mode 100644 index 0000000..bf9fc89 --- /dev/null +++ b/doc/source/sphinxpolicygen.rst @@ -0,0 +1,48 @@ +==================================== +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 |