diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 9d86cd31f2..fe9b39f5f6 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 - gmr - Upgrade Guide - upgrade-to-hardware-types - Release Notes - Troubleshooting FAQ - -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 - Configuring Node Inspection - Configuring RAID during deployment - Configuring to boot from volume - Security considerations for your Bare Metal installation - Adopting Nodes in an ACTIVE state - Configuring for Multi-tenant Networking - Configuring for port groups - Configuring node web or serial console - Emitting software metrics - Auditing API Traffic - Notifications - Ceph Object Gateway support - /configuration/sample-config - /configuration/sample-policy + Enabling Drivers + Ironic Python Agent + Node Hardware Inspection + Node Cleaning + Node Adoption + RAID Configuration + Configuring to boot from volume + Multi-tenant Networking + Port Groups + Configuring Web or Serial Console + Enabling Notifications + Ceph Object Gateway + Emitting Software Metrics + Auditing API Traffic + Service State Reporting + Upgrade Guide + Security + Troubleshooting FAQ Dashboard Integration --------------------- diff --git a/doc/source/admin/upgrade-guide.rst b/doc/source/admin/upgrade-guide.rst index 86eea51654..7d39b5d4e6 100644 --- a/doc/source/admin/upgrade-guide.rst +++ b/doc/source/admin/upgrade-guide.rst @@ -320,6 +320,11 @@ Upgrading from Ocata to Pike Other upgrade instructions are in the `Pike release notes `_. +.. 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 + Sample Config File + Policies + Sample Policy File 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 `. +.. 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 e6a42e2e75..e28fbb1dbb 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 https://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 - Further Considerations for the Agent Drivers - Bare Metal API References ========================= @@ -90,6 +94,11 @@ Contributor Guide contributor/index +Release Notes +============= + +`Release Notes `_ + Indices and tables ================== diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index c32955ad5f..e887370321 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