From 9f92d3a83e5af7084ba33786d882b09763cea569 Mon Sep 17 00:00:00 2001 From: zhurong Date: Tue, 31 Jul 2018 13:38:46 +0800 Subject: [PATCH] Docs: Autogenerate config documentation Ensure the documentation is kept up to date by automatically generating it from the source when the docs are built. Change-Id: I3f7e61de7534a44e5d0a4ce96aaed43f4e8951ff --- .gitignore | 2 + doc/source/_static/policy.yaml.sample | 139 ------------------ ...configure_cloud_foundry_service_broker.rst | 0 .../figures/add-interface.png | Bin .../figures/network-topology-1.png | Bin .../figures/network-topology-2.png | Bin doc/source/admin/index.rst | 2 + doc/source/admin/murano_policies.rst | 2 +- .../net_configuration.rst} | 9 +- doc/source/conf.py | 18 ++- doc/source/configuration/config-options.rst | 9 ++ doc/source/configuration/index.rst | 7 +- doc/source/configuration/sample_config.rst | 12 ++ doc/source/configuration/sample_policy.rst | 18 +++ 14 files changed, 66 insertions(+), 152 deletions(-) delete mode 100644 doc/source/_static/policy.yaml.sample rename doc/source/{configuration => admin}/configure_cloud_foundry_service_broker.rst (100%) rename doc/source/{configuration => admin}/figures/add-interface.png (100%) rename doc/source/{configuration => admin}/figures/network-topology-1.png (100%) rename doc/source/{configuration => admin}/figures/network-topology-2.png (100%) rename doc/source/{configuration/configuration.rst => admin/net_configuration.rst} (97%) create mode 100644 doc/source/configuration/config-options.rst create mode 100644 doc/source/configuration/sample_config.rst create mode 100644 doc/source/configuration/sample_policy.rst diff --git a/.gitignore b/.gitignore index 7e3e60562..9e25b4cb8 100644 --- a/.gitignore +++ b/.gitignore @@ -37,6 +37,8 @@ api-ref/build/ #Autogenerated Documentation doc/source/api +doc/source/_static/murano.conf.sample +doc/source/_static/murano.policy.yaml.sample #Config file for functional tests murano/tests/functional/engine/config.conf diff --git a/doc/source/_static/policy.yaml.sample b/doc/source/_static/policy.yaml.sample deleted file mode 100644 index 950648061..000000000 --- a/doc/source/_static/policy.yaml.sample +++ /dev/null @@ -1,139 +0,0 @@ -# -#"context_is_admin": "role:admin" - -# -#"admin_api": "is_admin:True" - -# -#"default": "" - -# Excute an available action on a deployed environment, -# retrieve the task status of an executed action, or retrieve the -# result of -# an executed static action. -# POST v1/environments/{environment_id}/actions/{action_id} -# GET v1/environments/{environment_id}/actions/{task_id} -# POST v1/actions -#"execute_action": "rule:default" - -# Show category details or list all categories in the -# application catalog. -# GET /v1/catalog/categories/{category_id} -# GET /v1/catalog/categories -#"get_category": "rule:default" - -# Delete a category. -# DELETE /v1/catalog/categories/{category_id} -#"delete_category": "rule:admin_api" - -# Create a category. -# POST /v1/catalog/categories -#"add_category": "rule:admin_api" - -# List deployments for an environment. -# GET /v1/environments/{env_id}/deployments -#"list_deployments": "rule:default" - -# List deployments for all environments in a project. -# GET /v1/deployments -#"list_deployments_all_environments": "rule:default" - -# Show deployment status details for a deployment. -# GET /v1/environments/{env_id}/deployments/{deployment_id} -#"statuses_deployments": "rule:default" - -# List environments in a project. -# GET /v1/environments -#"list_environments": "rule:default" - -# List environments across all projects. -# GET /v1/environments?all_tenants=true -#"list_environments_all_tenants": "rule:admin_api" - -# Show details for an environment or shows the environment model. -# GET /v1/environments/{environment_id} -# GET /v1/environments/{environment_id}/model -#"show_environment": "rule:default" - -# Update or rename an environment. -# PUT /v1/environments/{environment_id} -# PATCH /v1/environments/{environment_id}/model -#"update_environment": "rule:default" - -# Create an environment or create an environment and session from an -# environment template. -# POST /v1/environments/{environment_id} -# POST /v1/templates/{env_template_id}/create-environment -#"create_environment": "rule:default" - -# Delete an environment. -# DELETE /v1/environments/{environment_id} -#"delete_environment": "rule:default" - -# List environment templates in a project. -# GET /v1/templates -#"list_env_templates": "rule:default" - -# Create an environment template. -# POST /v1/templates -#"create_env_template": "rule:default" - -# Show environment template details. -# GET /v1/templates/{env_template_id} -#"show_env_template": "rule:default" - -# Update an environment template. -# PUT /v1/templates/{env_template_id} -#"update_env_template": "rule:default" - -# Delete an environment template. -# DELETE /v1/templates/{env_template_id} -#"delete_env_template": "rule:default" - -# Clone an environment template. -# POST /v1/templates/{env_template_id}/clone -#"clone_env_template": "rule:default" - -# Returns either detailed package information or -# information specific to the package's UI or logo. In addition, -# checks for the -# existence of a given package. -# GET /v1/catalog/packages/{package_id} -# GET /v1/catalog/packages -# GET /v1/catalog/packages/{package_id}/ui -# GET /v1/catalog/packages/{package_id}/logo -#"get_package": "rule:default" - -# Upload a package to the application catalog. -# POST /v1/catalog/packages -#"upload_package": "rule:default" - -# Update package information for a given package. -# PATCH /v1/catalog/packages/{package_id} -#"modify_package": "rule:default" - -# Publicize a package across all projects. Grants users in -# any project the ability to use the package. Enforced only when -# `is_public` -# parameter is set to True in the request body of the `update` or -# `upload` -# package request. -# PATCH /v1/catalog/packages/{package_id} -# POST /v1/catalog/packages -#"publicize_package": "rule:admin_api" - -# Either update, delete or check for the existence of a -# public package. Only enforced when the package is public. -# PATCH /v1/catalog/packages/{package_id} -# DELETE /v1/catalog/packages/{package_id} -# GET /v1/catalog/packages -#"manage_public_package": "rule:default" - -# Delete a given package. -# DELETE /v1/catalog/packages/{package_id} -#"delete_package": "rule:default" - -# Download a package from the application catalog. -# GET /v1/catalog/packages/{package_id}/download -#"download_package": "rule:default" - diff --git a/doc/source/configuration/configure_cloud_foundry_service_broker.rst b/doc/source/admin/configure_cloud_foundry_service_broker.rst similarity index 100% rename from doc/source/configuration/configure_cloud_foundry_service_broker.rst rename to doc/source/admin/configure_cloud_foundry_service_broker.rst diff --git a/doc/source/configuration/figures/add-interface.png b/doc/source/admin/figures/add-interface.png similarity index 100% rename from doc/source/configuration/figures/add-interface.png rename to doc/source/admin/figures/add-interface.png diff --git a/doc/source/configuration/figures/network-topology-1.png b/doc/source/admin/figures/network-topology-1.png similarity index 100% rename from doc/source/configuration/figures/network-topology-1.png rename to doc/source/admin/figures/network-topology-1.png diff --git a/doc/source/configuration/figures/network-topology-2.png b/doc/source/admin/figures/network-topology-2.png similarity index 100% rename from doc/source/configuration/figures/network-topology-2.png rename to doc/source/admin/figures/network-topology-2.png diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index b50a9808e..458c97f90 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -18,5 +18,7 @@ Deploying Murano murano_agent policy_enf using_glare.rst + net_configuration + configure_cloud_foundry_service_broker admin_troubleshooting appdev-guide/developer_index diff --git a/doc/source/admin/murano_policies.rst b/doc/source/admin/murano_policies.rst index 2a4aa4014..6f56cacdd 100644 --- a/doc/source/admin/murano_policies.rst +++ b/doc/source/admin/murano_policies.rst @@ -112,4 +112,4 @@ For reference: Default Murano Policies ----------------------- -.. literalinclude:: ../_static/policy.yaml.sample +.. literalinclude:: ../_static/murano.policy.yaml.sample diff --git a/doc/source/configuration/configuration.rst b/doc/source/admin/net_configuration.rst similarity index 97% rename from doc/source/configuration/configuration.rst rename to doc/source/admin/net_configuration.rst index f58c52ca7..d55c2c394 100644 --- a/doc/source/configuration/configuration.rst +++ b/doc/source/admin/net_configuration.rst @@ -1,11 +1,6 @@ -.. _configuration: - -============= -Configuration -============= - +===================== Network configuration -~~~~~~~~~~~~~~~~~~~~~ +===================== Murano may work in various networking environments and is capable of detecting the current network configuration and choosing appropriate settings diff --git a/doc/source/conf.py b/doc/source/conf.py index 68ff9f66c..fd32819f5 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -33,9 +33,16 @@ sys.path.insert(0, os.path.abspath('./')) # 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.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.todo', 'sphinx.ext.coverage', - 'sphinx.ext.viewcode', 'sphinxcontrib.httpdomain',] + 'oslo_config.sphinxconfiggen', + 'oslo_config.sphinxext', + 'oslo_policy.sphinxext', + 'oslo_policy.sphinxpolicygen', + 'sphinx.ext.viewcode', + 'sphinxcontrib.httpdomain',] if not on_rtd: extensions.append('openstackdocstheme') @@ -58,6 +65,13 @@ bug_project = 'murano' bug_tag = '' html_last_updated_fmt = '%Y-%m-%d %H:%M' +config_generator_config_file = '../../etc/oslo-config-generator/murano.conf' +sample_config_basename = '_static/murano' + +policy_generator_config_file = [ + ('../../etc/oslo-policy-generator/murano-policy-generator.conf', + '_static/murano'), +] # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the diff --git a/doc/source/configuration/config-options.rst b/doc/source/configuration/config-options.rst new file mode 100644 index 000000000..9064457cd --- /dev/null +++ b/doc/source/configuration/config-options.rst @@ -0,0 +1,9 @@ +========================================================= +Configuration options for the Application Catalog service +========================================================= + +The following options can be set in the ``/etc/murano/murano.conf`` config file. +A :doc:`sample configuration file ` is also available. + +.. show-options:: + :config-file: etc/oslo-config-generator/murano.conf diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst index 4e0b6d978..a8cde7cad 100644 --- a/doc/source/configuration/index.rst +++ b/doc/source/configuration/index.rst @@ -3,7 +3,8 @@ Configuration Guide =================== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - configuration - configure_cloud_foundry_service_broker + config-options + sample_config + sample_policy diff --git a/doc/source/configuration/sample_config.rst b/doc/source/configuration/sample_config.rst new file mode 100644 index 000000000..3e52bc395 --- /dev/null +++ b/doc/source/configuration/sample_config.rst @@ -0,0 +1,12 @@ +=========================== +Murano Configuration Sample +=========================== + +The following is a sample murano configuration for adaptation and use. It is +auto-generated from murano when this documentation is built, so if you are +having issues with an option, please compare your version of murano with the +version of this documentation. + +The sample configuration can also be downloaded in `file form <../_static/murano.conf.sample>`_. + +.. literalinclude:: ../_static/murano.conf.sample diff --git a/doc/source/configuration/sample_policy.rst b/doc/source/configuration/sample_policy.rst new file mode 100644 index 000000000..b34a463ba --- /dev/null +++ b/doc/source/configuration/sample_policy.rst @@ -0,0 +1,18 @@ +==================== +Murano Sample Policy +==================== + +The following is a sample murano policy file that has been auto-generated +from default policy values in code. If you're using the default policies, then +the maintenance of this file is not necessary, and it should not be copied into +a deployment. Doing so will result in duplicate policy definitions. It is here +to help explain which policy operations protect specific murano APIs, but it +is not suggested to copy and paste into a deployment unless you're planning on +providing a different policy for an operation that is not the default. + +If you wish build a policy file, you can also use ``tox -e genpolicy`` to +generate it. + +The sample policy file can also be downloaded in `file form <../_static/murano.policy.yaml.sample>`_. + +.. literalinclude:: ../_static/murano.policy.yaml.sample