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 <arnaud.morin@gmail.com>

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.

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

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
+</_static/mistral.conf.sample>`.
+
+.. 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
+

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 <config-guide>`: Detailed
+  configuration guides for various parts of your Mistral system.
+
+* :doc:`Config Reference <config-reference>`: A complete reference of all
+  configuration options available in the ``mistral.conf`` file.
+
+.. only:: html
+
+   * :doc:`Sample Config File <config-sample>`: 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
+   config-guide.rst
-   ../configuration/policy-guide.rst
+   config-reference.rst
-   ../configuration/samples/index.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 <policy-reference>`: A complete reference of all
+  policy points in mistral and what they impact.
+
+.. only:: html
+
+   * :doc:`Sample Policy File <policy-sample>`: 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

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
+   For a sample configuration file, refer to :doc:`policy-sample`.
-configuration file, refer to :doc:`samples/policy-yaml`.
 
 .. show-policy::
-   :config-file: ../../tools/config/policy-generator.mistral.conf
+   :config-file: tools/config/policy-generator.mistral.conf

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
 

doc/source/admin/configuration/samples/index.rst

@@ -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

doc/source/admin/install/index.rst

@@ -1,6 +1,6 @@
-==========================
+==================
-Mistral Installation Guide
+Installation Guide
-==========================
+==================
 
 .. toctree::
    :maxdepth: 1

doc/source/admin/upgrade_guide.rst

@@ -1,5 +1,6 @@
-Mistral Upgrade Guide
+=============
-=====================
+Upgrade Guide
+=============
 
 Database upgrade
 ----------------

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

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