From 38fd6d5d30e9b61de16e9cd017ff51afd51b4ab6 Mon Sep 17 00:00:00 2001 From: Arnaud M Date: Wed, 9 Oct 2024 00:46:01 +0200 Subject: [PATCH] Update documentation * Add configuration reference * Add configuration sample * Change some title to remove redundant info * Re-organize doc Change-Id: Ide9005c496997c7c216affc7df00f1ac264883da Signed-off-by: Arnaud M --- .../admin/configuration/config-guide.rst | 5 +- .../admin/configuration/config-reference.rst | 12 +++ .../admin/configuration/config-sample.rst | 21 +++++ doc/source/admin/configuration/index.rst | 77 +++++++++++++++++-- ...{policy-guide.rst => policy-reference.rst} | 16 ++-- .../policy-yaml.rst => policy-sample.rst} | 2 +- .../admin/configuration/samples/index.rst | 11 --- doc/source/admin/install/index.rst | 6 +- doc/source/admin/upgrade_guide.rst | 5 +- doc/source/conf.py | 10 ++- tools/config/config-generator.mistral.conf | 3 + 11 files changed, 131 insertions(+), 37 deletions(-) create mode 100644 doc/source/admin/configuration/config-reference.rst create mode 100644 doc/source/admin/configuration/config-sample.rst rename doc/source/admin/configuration/{policy-guide.rst => policy-reference.rst} (61%) rename doc/source/admin/configuration/{samples/policy-yaml.rst => policy-sample.rst} (88%) delete mode 100644 doc/source/admin/configuration/samples/index.rst diff --git a/doc/source/admin/configuration/config-guide.rst b/doc/source/admin/configuration/config-guide.rst index 05bad67b9..714049e41 100644 --- a/doc/source/admin/configuration/config-guide.rst +++ b/doc/source/admin/configuration/config-guide.rst @@ -1,5 +1,6 @@ -Mistral Configuration Guide -=========================== +=================== +Configuration Guide +=================== Mistral configuration is needed for getting Mistral work correctly either with real OpenStack environment or without OpenStack environment. diff --git a/doc/source/admin/configuration/config-reference.rst b/doc/source/admin/configuration/config-reference.rst new file mode 100644 index 000000000..372041ee8 --- /dev/null +++ b/doc/source/admin/configuration/config-reference.rst @@ -0,0 +1,12 @@ +======================= +Configuration Reference +======================= + +The following is an overview of all available configuration options in Mistral. + +.. only:: html + + For a sample configuration file, refer to :doc:`config-sample`. + +.. show-options:: + :config-file: tools/config/config-generator.mistral.conf diff --git a/doc/source/admin/configuration/config-sample.rst b/doc/source/admin/configuration/config-sample.rst new file mode 100644 index 000000000..43089ceb8 --- /dev/null +++ b/doc/source/admin/configuration/config-sample.rst @@ -0,0 +1,21 @@ +============ +mistral.conf +============ + +The following is a sample mistral configuration for adaptation and use. For a +detailed overview of all available configuration options, refer to +:doc:`/admin/configuration/config-reference`. + +The sample configuration can also be viewed in :download:`file form +`. + +.. important:: + + The sample configuration file is auto-generated from mistral when this + documentation is built. You must ensure your version of mistral matches the + version of this documentation. + +.. only:: html + + .. literalinclude:: /_static/mistral.conf.sample + diff --git a/doc/source/admin/configuration/index.rst b/doc/source/admin/configuration/index.rst index 1dffb7a6f..234088d37 100644 --- a/doc/source/admin/configuration/index.rst +++ b/doc/source/admin/configuration/index.rst @@ -1,10 +1,73 @@ -====================================== -Mistral Configuration and Policy Guide -====================================== +============================== +Configuration and Policy Guide +============================== +The static configuration for mistral lives in two main files: ``mistral.conf`` +and ``policy.yaml``. These are described below. + +Configuration +------------- + +Mistral, like most OpenStack projects, uses INI-style configuration files to +configure various services and utilities. This functionality is provided by the +`oslo.config` project. *oslo.config* supports loading configuration from both +individual configuration files and a directory of configuration files. By +default, mistral will search for a config file named +``/etc/mistral/mistral.conf``. + +More information on how you can use the configuration options to configure +services and what configuration options are available can be found below. + +* :doc:`Configuration Guide `: Detailed + configuration guides for various parts of your Mistral system. + +* :doc:`Config Reference `: A complete reference of all + configuration options available in the ``mistral.conf`` file. + +.. only:: html + + * :doc:`Sample Config File `: A sample config + file with inline documentation. + +.. # NOTE(amorin): This is the section where we hide things that we don't + # actually want in the table of contents but sphinx build would fail if + # they aren't in the toctree somewhere. .. toctree:: - :maxdepth: 2 + :hidden: - ../configuration/config-guide.rst - ../configuration/policy-guide.rst - ../configuration/samples/index.rst + config-guide.rst + config-reference.rst + config-sample.rst + +Policy +------ + +Mistral, like most OpenStack projects, uses a policy language to restrict +permissions on REST API actions. This functionality is provided by the +`oslo.policy` project. *oslo.policy* supports loading policy configuration +from both an individual configuration file, which defaults to ``policy.yaml``, +and one or more directories of configuration files, which defaults to +``policy.d``. These must be located in the same directory as the +``mistral.conf`` file(s). This behavior can be overridden by setting the +:oslo.config:option:`oslo_policy.policy_file` and +:oslo.config:option:`oslo_policy.policy_dirs` configuration options. + +More information on how mistral's policy configuration works and about what +policies are available can be found below. + +* :doc:`Policy Reference `: A complete reference of all + policy points in mistral and what they impact. + +.. only:: html + + * :doc:`Sample Policy File `: A sample mistral + policy file with inline documentation. + +.. # NOTE(amorin): This is the section where we hide things that we don't + # actually want in the table of contents but sphinx build would fail if + # they aren't in the toctree somewhere. +.. toctree:: + :hidden: + + policy-reference.rst + policy-sample.rst diff --git a/doc/source/admin/configuration/policy-guide.rst b/doc/source/admin/configuration/policy-reference.rst similarity index 61% rename from doc/source/admin/configuration/policy-guide.rst rename to doc/source/admin/configuration/policy-reference.rst index 5411b73d8..3b0cf169a 100644 --- a/doc/source/admin/configuration/policy-guide.rst +++ b/doc/source/admin/configuration/policy-reference.rst @@ -1,6 +1,8 @@ -============================ -Mistral Policy Configuration -============================ +================ +Policy Reference +================ + +The following is an overview of all available policies in Mistral. .. warning:: @@ -10,11 +12,9 @@ Mistral Policy Configuration .. __: https://docs.openstack.org/oslo.policy/latest/cli/oslopolicy-convert-json-to-yaml.html -Configuration -~~~~~~~~~~~~~ +.. only:: html -The following is an overview of all available policies in Mistral. For a sample -configuration file, refer to :doc:`samples/policy-yaml`. + For a sample configuration file, refer to :doc:`policy-sample`. .. show-policy:: - :config-file: ../../tools/config/policy-generator.mistral.conf + :config-file: tools/config/policy-generator.mistral.conf diff --git a/doc/source/admin/configuration/samples/policy-yaml.rst b/doc/source/admin/configuration/policy-sample.rst similarity index 88% rename from doc/source/admin/configuration/samples/policy-yaml.rst rename to doc/source/admin/configuration/policy-sample.rst index 79844bffa..85066bead 100644 --- a/doc/source/admin/configuration/samples/policy-yaml.rst +++ b/doc/source/admin/configuration/policy-sample.rst @@ -13,5 +13,5 @@ policy.yaml Use the ``policy.yaml`` file to define additional access controls that apply to the Mistral services: -.. literalinclude:: ../../../_static/mistral.policy.yaml.sample +.. literalinclude:: /_static/mistral.policy.yaml.sample diff --git a/doc/source/admin/configuration/samples/index.rst b/doc/source/admin/configuration/samples/index.rst deleted file mode 100644 index e76196d0e..000000000 --- a/doc/source/admin/configuration/samples/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -========================== -Sample configuration files -========================== - -Configuration files can alter how Mistral behaves at runtime and by default -are located in ``/etc/mistral/``. Links to sample configuration files can be -found below: - -.. toctree:: - - policy-yaml.rst diff --git a/doc/source/admin/install/index.rst b/doc/source/admin/install/index.rst index a350a086d..5b68a7c97 100644 --- a/doc/source/admin/install/index.rst +++ b/doc/source/admin/install/index.rst @@ -1,6 +1,6 @@ -========================== -Mistral Installation Guide -========================== +================== +Installation Guide +================== .. toctree:: :maxdepth: 1 diff --git a/doc/source/admin/upgrade_guide.rst b/doc/source/admin/upgrade_guide.rst index ac1309eaf..ed4406799 100644 --- a/doc/source/admin/upgrade_guide.rst +++ b/doc/source/admin/upgrade_guide.rst @@ -1,5 +1,6 @@ -Mistral Upgrade Guide -===================== +============= +Upgrade Guide +============= Database upgrade ---------------- diff --git a/doc/source/conf.py b/doc/source/conf.py index 6eb4235f5..d60114453 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -23,9 +23,7 @@ import sys # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('../../')) sys.path.insert(0, os.path.abspath('../')) -sys.path.insert(0, os.path.abspath('./')) # -- General configuration ---------------------------------------------------- @@ -40,6 +38,8 @@ extensions = [ 'openstackdocstheme', 'oslo_policy.sphinxext', 'oslo_policy.sphinxpolicygen', + 'oslo_config.sphinxconfiggen', + 'oslo_config.sphinxext', ] wsme_protocols = ['restjson'] @@ -54,12 +54,16 @@ master_doc = 'index' # General information about the project. project = 'Mistral' -copyright = '2023, Mistral Contributors' +copyright = '2023-present, Mistral Contributors' policy_generator_config_file = \ '../../tools/config/policy-generator.mistral.conf' sample_policy_basename = '_static/mistral' +config_generator_config_file = \ + '../../tools/config/config-generator.mistral.conf' +sample_config_basename = '_static/mistral' + # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. show_authors = False diff --git a/tools/config/config-generator.mistral.conf b/tools/config/config-generator.mistral.conf index 70197289e..0d9fb8968 100644 --- a/tools/config/config-generator.mistral.conf +++ b/tools/config/config-generator.mistral.conf @@ -1,4 +1,7 @@ [DEFAULT] +output_file = etc/mistral/mistral.conf.sample +wrap_width = 80 +summarize = true namespace = mistral.config namespace = oslo.db namespace = oslo.messaging