From adcbd324af61ad8070694d4e8fd988c738f177da Mon Sep 17 00:00:00 2001 From: Madhuri Kumari Date: Tue, 25 Jul 2017 13:30:59 +0530 Subject: [PATCH] [doc-migration] Add configuration folder for documentation This patch does the following: * Adds a configuration folder to contain automated generated config files for Ironic. * Adds `oslo_config.sphinxconfiggen` to the extensions list. * Adds `oslo_policy.sphinxpolicygen` to the extensions list. * Adds ironic-policy-generator.conf This is important for Ironic to be included in the list of services on https://docs.openstack.org/pike/configuration/ Change-Id: I51a7204ce00be2588e427c1951e8be7dc7a22647 Closes-bug: #1706176 --- .gitignore | 1 + doc/source/admin/index.rst | 5 ++--- doc/source/conf.py | 8 ++++++++ doc/source/configuration/index.rst | 10 ++++++++++ doc/source/configuration/sample-config.rst | 13 +++++++++++++ doc/source/configuration/sample-policy.rst | 12 ++++++++++++ doc/source/index.rst | 8 ++++++++ tools/policy/ironic-policy-generator.conf | 3 +++ tox.ini | 2 +- 9 files changed, 58 insertions(+), 4 deletions(-) create mode 100644 doc/source/configuration/index.rst create mode 100644 doc/source/configuration/sample-config.rst create mode 100644 doc/source/configuration/sample-policy.rst create mode 100644 tools/policy/ironic-policy-generator.conf diff --git a/.gitignore b/.gitignore index df0ae40bf9..5b517b23c4 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,7 @@ # Sphinx _build doc/source/contributor/api/ +_static/ironic # release notes build releasenotes/build diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 8af8abed50..1bb6b7dfe3 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -39,9 +39,8 @@ of ironic that may or may not be suitable to every situation. Auditing API Traffic Notifications Ceph Object Gateway support - Configuration Reference - Sample configuration file - + /configuration/sample-config + /configuration/sample-policy Dashboard Integration --------------------- diff --git a/doc/source/conf.py b/doc/source/conf.py index 3266fc0ef9..ed96dd3a54 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -21,6 +21,8 @@ extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.pecanwsme.rest', 'sphinxcontrib.seqdiag', 'wsmeext.sphinxext', + 'oslo_config.sphinxconfiggen', + 'oslo_policy.sphinxpolicygen', ] try: @@ -53,6 +55,12 @@ master_doc = 'index' project = u'Ironic' copyright = u'OpenStack Foundation' +config_generator_config_file = '../../tools/config/ironic-config-generator.conf' +sample_config_basename = '_static/ironic' + +policy_generator_config_file = '../../tools/policy/ironic-policy-generator.conf' +sample_policy_basename = '_static/ironic' + # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 0000000000..3d3f449eb7 --- /dev/null +++ b/doc/source/configuration/index.rst @@ -0,0 +1,10 @@ +Configuration Guide +------------------- + +Here are sample configuration files generated automatically for Ironic. + +.. toctree:: + :maxdepth: 1 + + 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 0000000000..afee149410 --- /dev/null +++ b/doc/source/configuration/sample-config.rst @@ -0,0 +1,13 @@ +============================ +Ironic Configuration Options +============================ + +The following is a sample Ironic configuration for adaptation and use. It is +auto-generated from Ironic when this documentation is built, so +if you find issues with an option, please compare your version of +Ironic with the version of this documentation. + +The sample configuration can also be downloaded as a :download:`file +`. + +.. literalinclude:: /_static/ironic.conf.sample diff --git a/doc/source/configuration/sample-policy.rst b/doc/source/configuration/sample-policy.rst new file mode 100644 index 0000000000..c817126129 --- /dev/null +++ b/doc/source/configuration/sample-policy.rst @@ -0,0 +1,12 @@ +============= +Ironic Policy +============= + +The following is a sample Ironic policy file, autogenerated from Ironic when +this documentation is built. To prevent conflicts, ensure your version of +Ironic aligns with the version of this documentation. + +The sample policy can also be downloaded as a :download:`file +`. + +.. literalinclude:: /_static/ironic.policy.yaml.sample diff --git a/doc/source/index.rst b/doc/source/index.rst index 45ac090c1c..4214b78838 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -38,6 +38,14 @@ Administrator Guide admin/index +Configuration Reference +======================= + +.. toctree:: + :maxdepth: 2 + + configuration/index + Driver References ================= diff --git a/tools/policy/ironic-policy-generator.conf b/tools/policy/ironic-policy-generator.conf new file mode 100644 index 0000000000..fda8ed608a --- /dev/null +++ b/tools/policy/ironic-policy-generator.conf @@ -0,0 +1,3 @@ +[DEFAULT] +output_file = etc/ironic/policy.json.sample +namespace = ironic.api diff --git a/tox.ini b/tox.ini index fc9ad55c7e..bf594a0d86 100644 --- a/tox.ini +++ b/tox.ini @@ -65,7 +65,7 @@ commands = sitepackages = False envdir = {toxworkdir}/venv commands = - oslopolicy-sample-generator --namespace=ironic.api --output-file=etc/ironic/policy.json.sample + oslopolicy-sample-generator --config-file=tools/policy/ironic-policy-generator.conf [testenv:debug] commands = oslo_debug_helper -t ironic/tests/unit {posargs}