Browse Source

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
changes/85/587285/2
zhurong 3 years ago
parent
commit
9f92d3a83e
  1. 2
      .gitignore
  2. 139
      doc/source/_static/policy.yaml.sample
  3. 0
      doc/source/admin/configure_cloud_foundry_service_broker.rst
  4. 0
      doc/source/admin/figures/add-interface.png
  5. 0
      doc/source/admin/figures/network-topology-1.png
  6. 0
      doc/source/admin/figures/network-topology-2.png
  7. 2
      doc/source/admin/index.rst
  8. 2
      doc/source/admin/murano_policies.rst
  9. 9
      doc/source/admin/net_configuration.rst
  10. 18
      doc/source/conf.py
  11. 9
      doc/source/configuration/config-options.rst
  12. 7
      doc/source/configuration/index.rst
  13. 12
      doc/source/configuration/sample_config.rst
  14. 18
      doc/source/configuration/sample_policy.rst

2
.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

139
doc/source/_static/policy.yaml.sample

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

0
doc/source/configuration/configure_cloud_foundry_service_broker.rst → doc/source/admin/configure_cloud_foundry_service_broker.rst

0
doc/source/configuration/figures/add-interface.png → doc/source/admin/figures/add-interface.png

Before

Width: 737  |  Height: 445  |  Size: 41 KiB

After

Width: 737  |  Height: 445  |  Size: 41 KiB

0
doc/source/configuration/figures/network-topology-1.png → doc/source/admin/figures/network-topology-1.png

Before

Width: 868  |  Height: 745  |  Size: 39 KiB

After

Width: 868  |  Height: 745  |  Size: 39 KiB

0
doc/source/configuration/figures/network-topology-2.png → doc/source/admin/figures/network-topology-2.png

Before

Width: 735  |  Height: 736  |  Size: 42 KiB

After

Width: 735  |  Height: 736  |  Size: 42 KiB

2
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

2
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

9
doc/source/configuration/configuration.rst → 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

18
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

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

7
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

12
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

18
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
Loading…
Cancel
Save