From af8f46b7f4fc62aa8802a449d04325a0d7e79ace Mon Sep 17 00:00:00 2001
From: Ilya Etingof <etingof@gmail.com>
Date: Tue, 8 Aug 2017 19:02:36 +0200
Subject: [PATCH] Configuration documentation migrated
Documentation layout aligned with the OS standards.
The admin page cleaned up - unrelated references moved
elsewhere linking merely admin pages.
The configuration page refactored, ironic.conf
and policy.conf documentation and samples
automatically generated by oslo_config.sphinxext.
Change-Id: I9075e2688f59ecd8ab5c489679f2c53d6294f28d
---
doc/source/admin/index.rst | 55 ++++++++--------------
doc/source/admin/upgrade-guide.rst | 5 ++
doc/source/conf.py | 2 +
doc/source/configuration/config.rst | 10 ++++
doc/source/configuration/index.rst | 16 +++++--
doc/source/configuration/policy.rst | 9 ++++
doc/source/configuration/sample-config.rst | 21 +++++----
doc/source/index.rst | 37 +++++++++------
doc/source/install/index.rst | 2 +-
doc/source/user/index.rst | 6 +--
10 files changed, 96 insertions(+), 67 deletions(-)
create mode 100644 doc/source/configuration/config.rst
create mode 100644 doc/source/configuration/policy.rst
diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst
index 3697e46499..af4d39c149 100644
--- a/doc/source/admin/index.rst
+++ b/doc/source/admin/index.rst
@@ -1,48 +1,31 @@
Administrator's Guide
=====================
-Installation & Operations
--------------------------
-
If you are a system administrator running Ironic, this section contains
-information that should help you understand how to deploy, operate, and upgrade
+information that may help you understand how to operate and upgrade
the services.
.. toctree::
:maxdepth: 1
- Installation Guide </install/index>
- gmr
- Upgrade Guide <upgrade-guide>
- upgrade-to-hardware-types
- Release Notes <http://docs.openstack.org/releasenotes/ironic/>
- Troubleshooting FAQ <troubleshooting>
-
-Configuration
--------------
-
-There are many aspects of the Bare Metal service which are environment
-specific. The following pages will be helpful in configuring specific aspects
-of ironic that may or may not be suitable to every situation.
-
-.. toctree::
- :maxdepth: 1
-
- Guide to Node Cleaning <cleaning>
- Configuring Node Inspection <inspection>
- Configuring RAID during deployment <raid>
- Configuring to boot from volume <boot-from-volume>
- Security considerations for your Bare Metal installation <security>
- Adopting Nodes in an ACTIVE state <adoption>
- Configuring for Multi-tenant Networking <multitenancy>
- Configuring for port groups <portgroups>
- Configuring node web or serial console <console>
- Emitting software metrics <metrics>
- Auditing API Traffic <api-audit-support>
- Notifications <notifications>
- Ceph Object Gateway support <radosgw>
- /configuration/sample-config
- /configuration/sample-policy
+ Enabling Drivers <drivers>
+ Ironic Python Agent <drivers/ipa>
+ Node Hardware Inspection <inspection>
+ Node Cleaning <cleaning>
+ Node Adoption <adoption>
+ RAID Configuration <raid>
+ Configuring to boot from volume <boot-from-volume>
+ Multi-tenant Networking <multitenancy>
+ Port Groups <portgroups>
+ Configuring Web or Serial Console <console>
+ Enabling Notifications <notifications>
+ Ceph Object Gateway <radosgw>
+ Emitting Software Metrics <metrics>
+ Auditing API Traffic <api-audit-support>
+ Service State Reporting <gmr>
+ Upgrade Guide <upgrade-guide>
+ Security <security>
+ Troubleshooting FAQ <troubleshooting>
Dashboard Integration
---------------------
diff --git a/doc/source/admin/upgrade-guide.rst b/doc/source/admin/upgrade-guide.rst
index 7441e7ae90..050e796caf 100644
--- a/doc/source/admin/upgrade-guide.rst
+++ b/doc/source/admin/upgrade-guide.rst
@@ -321,6 +321,11 @@ Upgrading from Ocata to Pike
Other upgrade instructions are in the `Pike release notes
<https://docs.openstack.org/releasenotes/ironic/pike.html>`_.
+.. toctree::
+ :maxdepth: 1
+
+ upgrade-to-hardware-types.rst
+
Upgrading from Newton to Ocata
==============================
diff --git a/doc/source/conf.py b/doc/source/conf.py
index ed96dd3a54..5436dd77a4 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -21,7 +21,9 @@ extensions = ['sphinx.ext.autodoc',
'sphinxcontrib.pecanwsme.rest',
'sphinxcontrib.seqdiag',
'wsmeext.sphinxext',
+ 'oslo_config.sphinxext',
'oslo_config.sphinxconfiggen',
+ 'oslo_policy.sphinxext',
'oslo_policy.sphinxpolicygen',
]
diff --git a/doc/source/configuration/config.rst b/doc/source/configuration/config.rst
new file mode 100644
index 0000000000..6b8a5c7cc9
--- /dev/null
+++ b/doc/source/configuration/config.rst
@@ -0,0 +1,10 @@
+=====================
+Configuration Options
+=====================
+
+The following is an overview of all available configuration options in
+Ironic. For a sample configuration file, refer to
+:doc:`sample-config`.
+
+.. show-options::
+ :config-file: tools/config/ironic-config-generator.conf
diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
index 3d3f449eb7..a21f4e558d 100644
--- a/doc/source/configuration/index.rst
+++ b/doc/source/configuration/index.rst
@@ -1,10 +1,16 @@
-Configuration Guide
--------------------
+=======================
+Configuration Reference
+=======================
-Here are sample configuration files generated automatically for Ironic.
+Many aspects of the Bare Metal service are specific to the environment
+it is deployed in. The following pages describe configuration
+options that can be used to adjust the service to your particular
+situation.
.. toctree::
:maxdepth: 1
- sample-config
- sample-policy
+ Configuration Options <config>
+ Sample Config File <sample-config>
+ Policies <policy>
+ Sample Policy File <sample-policy>
diff --git a/doc/source/configuration/policy.rst b/doc/source/configuration/policy.rst
new file mode 100644
index 0000000000..251e45c223
--- /dev/null
+++ b/doc/source/configuration/policy.rst
@@ -0,0 +1,9 @@
+========
+Policies
+========
+
+The following is an overview of all available policies in Ironic. For
+a sample configuration file, refer to :doc:`sample-policy`.
+
+.. show-policy::
+ :config-file: tools/policy/ironic-policy-generator.conf
diff --git a/doc/source/configuration/sample-config.rst b/doc/source/configuration/sample-config.rst
index afee149410..cfb8980fbc 100644
--- a/doc/source/configuration/sample-config.rst
+++ b/doc/source/configuration/sample-config.rst
@@ -1,13 +1,18 @@
-============================
-Ironic Configuration Options
-============================
+=========================
+Sample Configuration File
+=========================
-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 following is a sample Ironic configuration for adaptation and use. For a
+detailed overview of all available configuration options, refer to
+:doc:`config`.
-The sample configuration can also be downloaded as a :download:`file
+The sample configuration can also be viewed in :download:`file form
</_static/ironic.conf.sample>`.
+.. important::
+
+ The sample configuration file is auto-generated from Ironic when this
+ documentation is built. You must ensure your version of Ironic matches the
+ version of this documentation.
+
.. literalinclude:: /_static/ironic.conf.sample
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 4214b78838..77ed29f267 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -22,6 +22,22 @@ previous release of ironic, append the OpenStack release name to the URL; for
example, the ``ocata`` release is available at
http://docs.openstack.org/ironic/ocata/.
+Installation Guide
+==================
+
+.. toctree::
+ :maxdepth: 2
+
+ install/index
+
+Upgrade Guide
+=============
+
+.. toctree::
+ :maxdepth: 2
+
+ admin/upgrade-guide
+
User Guide
==========
@@ -38,26 +54,14 @@ Administrator Guide
admin/index
-Configuration Reference
-=======================
+Configuration Guide
+===================
.. toctree::
:maxdepth: 2
configuration/index
-Driver References
-=================
-
-Every driver author is expected to document the use and configuration of their
-driver. These pages are linked below.
-
-.. toctree::
- :maxdepth: 1
-
- Driver Documentation pages <admin/drivers>
- Further Considerations for the Agent Drivers <admin/drivers/ipa>
-
Bare Metal API References
=========================
@@ -90,6 +94,11 @@ Contributor Guide
contributor/index
+Release Notes
+=============
+
+`Release Notes <http://docs.openstack.org/releasenotes/ironic/>`_
+
Indices and tables
==================
diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst
index a71eaa13cf..45e5ec952f 100644
--- a/doc/source/install/index.rst
+++ b/doc/source/install/index.rst
@@ -1,5 +1,5 @@
=====================================
-Bare Metal service installation guide
+Bare Metal Service Installation Guide
=====================================
The Bare Metal service is a collection of components that provides support to
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
index d2650ade5d..8697235d56 100644
--- a/doc/source/user/index.rst
+++ b/doc/source/user/index.rst
@@ -1,8 +1,8 @@
.. _user-guide:
-======================
-Introduction to Ironic
-======================
+=============================
+Bare Metal Service User Guide
+=============================
Ironic is an OpenStack project which provisions bare metal (as opposed to
virtual) machines. It may be used independently or as part of an OpenStack