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
This commit is contained in:
zhurong 2018-07-31 13:38:46 +08:00
parent 0ae29f63e2
commit 9f92d3a83e
14 changed files with 66 additions and 152 deletions

2
.gitignore vendored
View File

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

View File

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

View File

Before

Width:  |  Height:  |  Size: 41 KiB

After

Width:  |  Height:  |  Size: 41 KiB

View File

Before

Width:  |  Height:  |  Size: 39 KiB

After

Width:  |  Height:  |  Size: 39 KiB

View File

Before

Width:  |  Height:  |  Size: 42 KiB

After

Width:  |  Height:  |  Size: 42 KiB

View File

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

View File

@ -112,4 +112,4 @@ For reference:
Default Murano Policies
-----------------------
.. literalinclude:: ../_static/policy.yaml.sample
.. literalinclude:: ../_static/murano.policy.yaml.sample

View File

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

View File

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

View File

@ -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 <sample_config>` is also available.
.. show-options::
:config-file: etc/oslo-config-generator/murano.conf

View File

@ -3,7 +3,8 @@ Configuration Guide
===================
.. toctree::
:maxdepth: 2
:maxdepth: 1
configuration
configure_cloud_foundry_service_broker
config-options
sample_config
sample_policy

View File

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

View File

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