From dfca9b1943d1c64533ef754bd3c248dacdd3d627 Mon Sep 17 00:00:00 2001 From: Dmitriy Rabotyagov Date: Wed, 31 Mar 2021 13:10:52 +0300 Subject: [doc] Add configuration reference Config reference has been dropped for some reason several releases before. We return configuration reference along with policy to the docs. Change-Id: I0927466d18eca5572932fcf9e2ca6349b11ca847 --- doc/source/conf.py | 22 +++++++++++++++++++--- doc/source/reference/conf-file.rst | 24 ++++++++++++++++++++++++ doc/source/reference/conf.rst | 11 +++++++++++ doc/source/reference/index.rst | 4 ++++ doc/source/reference/policy-file.rst | 20 ++++++++++++++++++++ doc/source/reference/policy.rst | 14 ++++++++++++++ 6 files changed, 92 insertions(+), 3 deletions(-) create mode 100644 doc/source/reference/conf-file.rst create mode 100644 doc/source/reference/conf.rst create mode 100644 doc/source/reference/policy-file.rst create mode 100644 doc/source/reference/policy.rst (limited to 'doc') diff --git a/doc/source/conf.py b/doc/source/conf.py index fbbd02cc..bde81cf1 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -14,9 +14,16 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.todo', - 'sphinx.ext.viewcode', - 'openstackdocstheme', - 'stevedore.sphinxext'] + 'sphinx.ext.autodoc', + 'sphinx.ext.coverage', + 'sphinx.ext.viewcode', + 'openstackdocstheme', + 'stevedore.sphinxext', + 'oslo_config.sphinxconfiggen', + 'oslo_config.sphinxext', + 'oslo_policy.sphinxpolicygen', + 'oslo_policy.sphinxext', +] # openstackdocstheme options openstackdocs_repo_name = 'openstack/trove' @@ -25,6 +32,15 @@ openstack_auto_name = False openstackdocs_bug_tag = '' html_theme = 'openstackdocs' +# sphinxcontrib.apidoc options +config_generator_config_file = ( + '../../tools/trove-config-generator.conf') +sample_config_basename = '_static/trove' + +policy_generator_config_file = ( + '../../tools/trove-policy-generator.conf') +sample_policy_basename = '_static/trove' + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/doc/source/reference/conf-file.rst b/doc/source/reference/conf-file.rst new file mode 100644 index 00000000..9b8dd2f8 --- /dev/null +++ b/doc/source/reference/conf-file.rst @@ -0,0 +1,24 @@ +.. _trove-config-file: + +------------------------------- +Trove Sample Configuration File +------------------------------- + +Configure Trove by editing /etc/trove/trove.conf. + +No config file is provided with the source code, it will be created during +the installation. In case where no configuration file was installed, one +can be easily created by running:: + + tox -e genconfig + + +To see configuration options available, please refer to :ref:`trove-conf`. + +.. only:: html + + The following is a sample Trove configuration for adaptation and use. + It is auto-generated from Trove when this documentation is built, and + can also be viewed in `file form <../_static/trove.conf.sample>`_. + + .. literalinclude:: ../_static/trove.conf.sample diff --git a/doc/source/reference/conf.rst b/doc/source/reference/conf.rst new file mode 100644 index 00000000..7aeecf07 --- /dev/null +++ b/doc/source/reference/conf.rst @@ -0,0 +1,11 @@ +.. _trove-conf: + +--------------------------- +Trove Configuration Options +--------------------------- + +The following is an overview of all available configuration options in Trove. +To see sample configuration file, see :ref:`trove-config-file`. + +.. show-options:: + :config-file: tools/trove-config-generator.conf diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 862b64e0..14bfb911 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -6,4 +6,8 @@ :maxdepth: 1 notifier.rst + conf.rst + conf-file.rst + policy.rst + policy-file.rst trove_api_extensions.rst diff --git a/doc/source/reference/policy-file.rst b/doc/source/reference/policy-file.rst new file mode 100644 index 00000000..7b3157f2 --- /dev/null +++ b/doc/source/reference/policy-file.rst @@ -0,0 +1,20 @@ +.. _trove-policy-file: + +=========== +policy.yaml +=========== + +.. warning:: + + JSON formatted policy file is deprecated since Trove 15.0.0 (Wallaby). + This `oslopolicy-convert-json-to-yaml`__ tool will migrate your existing + JSON-formatted policy file to YAML in a backward-compatible way. + +.. __: https://docs.openstack.org/oslo.policy/latest/cli/oslopolicy-convert-json-to-yaml.html + +To see available policies, refer to :ref:`policy-configuration`. + +Use the ``policy.yaml`` file to define additional access controls that will be +applied to Trove: + +.. literalinclude:: ../_static/trove.policy.yaml.sample diff --git a/doc/source/reference/policy.rst b/doc/source/reference/policy.rst new file mode 100644 index 00000000..ece2beac --- /dev/null +++ b/doc/source/reference/policy.rst @@ -0,0 +1,14 @@ +.. _policy-configuration: + +-------------------------- +Trove Policy Configuration +-------------------------- + +The following is an overview of all available policies in Aodh. + +For a sample policy file refer to the :ref:`trove-policy-file` or +run ``tox -egenpolicy`` in the repo folder and the new file will +be located in etc/trove/policy.yaml.sample + +.. show-policy:: + :config-file: tools/trove-policy-generator.conf -- cgit v1.2.1