Reorganize the documentation front page

This is largely inspired by the excellent feedback we got from David
Welsch, although this patch is only a very early first step towards
where we want to be with the documentation.

First, I'm splitting the large administrator guide into several large
sections: features, operation, architecture. Some of their topic might
actually find a better home outside of the administrator guide, but I
don't go that far in this change.

Second, I'm grouping several separate things together with the larger
topics:
- API topics are relevant for users and are grouped with the user guide
- Configuration guide and release notes are grouped with the
  administrator guide.
- The command reference is renamed for clarity and also grouped with the
  administrator guide since these are not user-visible commands.
- I'm dropping the "Advanced topics" subsection. While I like its
  intention (and I think it was me who added it in the first place),
  it's clear that such separation makes these topics much less
  discoverable.

Third, I'm playing with :maxdepth: here to make the sub-pages more
informative.

Change-Id: Icd0a35b252136b7da107c6346c48473cf1b99bcb

doc/source/admin/architecture.rst

@@ -0,0 +1,8 @@
+Architecture and Implementation Details
+=======================================
+
+.. toctree::
+  :maxdepth: 1
+
+   Agent Token <agent-token>
+   Steps <steps>

doc/source/admin/dashboard.rst

@@ -0,0 +1,8 @@
+Dashboard Integration
+---------------------
+
+A plugin for the OpenStack Dashboard (horizon) service is under development.
+Documentation for that can be found within the ironic-ui project.
+
+* :ironic-ui-doc:`Dashboard (horizon) plugin <>`
+

doc/source/admin/features.rst

@@ -0,0 +1,27 @@
+Bare Metal Service Features
+===========================
+
+.. toctree::
+  :maxdepth: 1
+
+   Hardware Inspection <inspection>
+   Deployment <node-deployment>
+   Cleaning <cleaning>
+   Adoption <adoption>
+   Retirement <retirement>
+   RAID Configuration <raid>
+   BIOS Settings <bios>
+   Firmware Updates <firmware-updates>
+   Node Rescuing <rescue>
+   Booting from Volume <boot-from-volume>
+   Configuring Web or Serial Console <console>
+   Enabling Notifications <notifications>
+   Node Multi-Tenancy <node-multitenancy>
+   Booting a Ramdisk or an ISO <ramdisk-boot>
+   Hardware Burn-in <hardware-burn-in>
+   Vendor Passthru <vendor-passthru>
+   Servicing <servicing>
+   Windows Images <building-windows-images>
+   Deploying without BMC Credentials <agent-power>
+   Layer 3 or DHCP-less Ramdisk Booting <dhcp-less>
+   Deploying with Anaconda <anaconda-deploy-interface>

doc/source/admin/index.rst

@@ -5,74 +5,15 @@ If you are a system administrator running Ironic, this section contains
 information that may help you understand how to operate and upgrade
 the services.
 
-.. toctree::
-  :maxdepth: 1
-
-   Ironic Python Agent <drivers/ipa>
-   Node Hardware Inspection <inspection>
-   Node Deployment <node-deployment>
-   Node Cleaning <cleaning>
-   Node Adoption <adoption>
-   Node Retirement <retirement>
-   RAID Configuration <raid>
-   BIOS Settings <bios>
-   Firmware Updates <firmware-updates>
-   Node Rescuing <rescue>
-   Configuring to boot from volume <boot-from-volume>
-   Multi-tenant Networking <multitenancy>
-   Port Groups <portgroups>
-   Configuring Web or Serial Console <console>
-   Enabling Notifications <notifications>
-   Conductor Groups <conductor-groups>
-   Upgrade Guide <upgrade-guide>
-   Security <security>
-   Troubleshooting FAQ <troubleshooting>
-   Power Synchronization <power-sync>
-   Node Multi-Tenancy <node-multitenancy>
-   Fast-Track Deployment <fast-track>
-   Booting a Ramdisk or an ISO <ramdisk-boot>
-   Hardware Burn-in <hardware-burn-in>
-   Vendor Passthru <vendor-passthru>
-   Servicing <servicing>
-   Authentication Support for Instance Images <user-image-basic-auth>
-
-Drivers, Hardware Types and Hardware Interfaces
------------------------------------------------
-
 .. toctree::
   :maxdepth: 3
 
   drivers
-
+  features
-Advanced Topics
+  operation
----------------
+  architecture
-
-.. toctree::
-  :maxdepth: 1
-
-   Ceph Object Gateway <radosgw>
-   Windows Images <building-windows-images>
-   Emitting Software Metrics <metrics>
-   Auditing API Traffic <api-audit-support>
-   Service State Reporting <gmr>
-   Agent Token <agent-token>
-   Deploying without BMC Credentials <agent-power>
-   Layer 3 or DHCP-less Ramdisk Booting <dhcp-less>
-   Tuning Ironic <tuning>
-   Role Based Access Control <secure-rbac>
-   Deploying with Anaconda <anaconda-deploy-interface>
-   Steps <steps>
-   OVN Networking <ovn-networking>
 
 .. toctree::
   :hidden:
 
   deploy-steps
-
-Dashboard Integration
----------------------
-
-A plugin for the OpenStack Dashboard (horizon) service is under development.
-Documentation for that can be found within the ironic-ui project.
-
-* :ironic-ui-doc:`Dashboard (horizon) plugin <>`

doc/source/admin/operation.rst

@@ -0,0 +1,24 @@
+Configuration and Operation
+===========================
+
+.. toctree::
+  :maxdepth: 1
+
+   Ironic Python Agent <drivers/ipa>
+   Multi-tenant Networking <multitenancy>
+   Port Groups <portgroups>
+   Conductor Groups <conductor-groups>
+   Security <security>
+   Troubleshooting FAQ <troubleshooting>
+   Power Synchronization <power-sync>
+   Fast-Track Deployment <fast-track>
+   Authentication for Instance Images <user-image-basic-auth>
+   OVN Networking <ovn-networking>
+   Ceph Object Gateway <radosgw>
+   Emitting Software Metrics <metrics>
+   Auditing API Traffic <api-audit-support>
+   Service State Reporting <gmr>
+   Tuning Ironic <tuning>
+   Role Based Access Control <secure-rbac>
+   Dashboard Integration <dashboard>
+   Upgrade Guide <upgrade-guide>

doc/source/cli/index.rst

@@ -1,5 +1,5 @@
-Command References
+Administrator Command References
-==================
+================================
 
 Here are references for commands not elsewhere documented.
 

doc/source/configuration/index.rst

@@ -8,7 +8,7 @@ options that can be used to adjust the service to your particular
 situation.
 
 .. toctree::
-  :maxdepth: 1
+  :maxdepth: 2
 
   Configuration Options <config>
   Policies <policy>

doc/source/index.rst

@@ -44,6 +44,13 @@ User Guide
 
   user/index
 
+.. toctree::
+  :maxdepth: 1
+
+  API Concept Guide <contributor/webapi>
+  API Reference (latest) <https://docs.openstack.org/api-ref/baremetal/>
+  API Version History <contributor/webapi-version-history>
+
 Administrator Guide
 ===================
 
@@ -55,39 +62,34 @@ Administrator Guide
 .. toctree::
   :maxdepth: 2
 
-  admin/index
+  admin/features
 
-Configuration Guide
+.. toctree::
-===================
+  :maxdepth: 2
+
+  admin/operation
+
+.. toctree::
+  :maxdepth: 2
+
+  cli/index
 
 .. toctree::
   :maxdepth: 2
 
   configuration/index
 
-Bare Metal API References
-=========================
-
-Ironic's REST API has changed since its first release, and continues to evolve
-to meet the changing needs of the community.  Here we provide a conceptual
-guide as well as more detailed reference documentation.
-
-.. toctree::
-  :maxdepth: 1
-
-  API Concept Guide <contributor/webapi>
-  API Reference (latest) <https://docs.openstack.org/api-ref/baremetal/>
-  API Version History <contributor/webapi-version-history>
-
-Command References
-==================
-
-Here are references for commands not elsewhere documented.
-
 .. toctree::
   :maxdepth: 2
 
-  cli/index
+  admin/architecture
+
+* `Release Notes <https://docs.openstack.org/releasenotes/ironic/>`_
+
+.. toctree::
+  :hidden:
+
+  admin/index
 
 Contributor Guide
 =================
@@ -97,11 +99,6 @@ Contributor Guide
 
    contributor/index
 
-Release Notes
-=============
-
-`Release Notes <https://docs.openstack.org/releasenotes/ironic/>`_
-
 .. only:: html
 
    Indices and tables