Sphinx Oslo 示例策略生成

注意

此扩展依赖于 oslopolicy-sample-generator，它需要代码中配置策略才能正常工作。请参阅 用法 指南以获取更多信息。

oslo.policy 包含一个 sphinx 扩展，用于在每次 sphinx 构建开始时生成一个示例策略文件。然后可以将此示例策略文件作为原始文件包含在您的文档中，例如通过 literalinclude 指令。

要激活此扩展，请将 oslo_policy.sphinxpolicygen 添加到 sphinx conf.py 中的扩展列表。启用后，您需要定义两个选项：policy_generator_config_file 和 sample_policy_basename。例如

policy_generator_config_file = '../../etc/nova/nova-policy-generator.conf'
sample_policy_basename = '_static/nova'

其中

policy_generator_config_file

用于 oslopolicy-sample-generator 工具的配置文件路径。可以是完整路径，也可以是相对于文档源目录 (app.srcdir) 的值。如果未指定此选项或无效，则将跳过示例策略文件生成。

为了处理需要生成多个文件的情况，此值可以是要生成文件的配置文件的路径和输出文件基本名的两部分元组的列表（在这种情况下，不应设置 sample_policy_basename）。

sample_policy_basename

输出文件的基本名称。将在此名称后附加 .policy.yaml.sample 扩展名以生成最终输出文件，并且路径相对于文档源目录 (app.srcdir)。因此，使用上面的示例，策略文件将输出到 _static/nova.policy.yaml.sample。如果未指定此选项，则文件将输出到 sample.policy.yaml。

exclude_deprecated

布尔值，默认值为 False，控制输出是否应包含弃用的策略信息或值，因为在某些情况下这些信息可能会造成混淆和误导。

配置完成后，您可以将此配置文件包含在您的源文件中

=============
Sample Policy
=============

Here is a sample policy file.

.. literalinclude:: _static/nova.policy.yaml.sample