Debian Codegraph @

doc/source/user/sphinxpolicygen.rst

raw
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