From 656f93b6e7a066c9a91150ecdd96ded4e6fad792 Mon Sep 17 00:00:00 2001
From: Dmitry Tantsur <dtantsur@protonmail.com>
Date: Fri, 21 Jun 2024 17:36:09 +0200
Subject: [PATCH] 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 | 8 ++++
doc/source/admin/dashboard.rst | 8 ++++
doc/source/admin/features.rst | 27 +++++++++++++
doc/source/admin/index.rst | 65 ++----------------------------
doc/source/admin/operation.rst | 24 +++++++++++
doc/source/cli/index.rst | 4 +-
doc/source/configuration/index.rst | 2 +-
doc/source/index.rst | 53 ++++++++++++------------
8 files changed, 98 insertions(+), 93 deletions(-)
create mode 100644 doc/source/admin/architecture.rst
create mode 100644 doc/source/admin/dashboard.rst
create mode 100644 doc/source/admin/features.rst
create mode 100644 doc/source/admin/operation.rst
diff --git a/doc/source/admin/architecture.rst b/doc/source/admin/architecture.rst
new file mode 100644
index 0000000000..682a69081f
--- /dev/null
+++ b/doc/source/admin/architecture.rst
@@ -0,0 +1,8 @@
+Architecture and Implementation Details
+=======================================
+
+.. toctree::
+ :maxdepth: 1
+
+ Agent Token <agent-token>
+ Steps <steps>
diff --git a/doc/source/admin/dashboard.rst b/doc/source/admin/dashboard.rst
new file mode 100644
index 0000000000..4a30e143e6
--- /dev/null
+++ b/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 <>`
+
diff --git a/doc/source/admin/features.rst b/doc/source/admin/features.rst
new file mode 100644
index 0000000000..d6dad3976e
--- /dev/null
+++ b/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>
diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst
index 3a19d2394d..7933f0d8cf 100644
--- a/doc/source/admin/index.rst
+++ b/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
-
-Advanced Topics
----------------
-
-.. 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>
+ features
+ operation
+ architecture
.. 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 <>`
diff --git a/doc/source/admin/operation.rst b/doc/source/admin/operation.rst
new file mode 100644
index 0000000000..751f2dc687
--- /dev/null
+++ b/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>
diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
index aa11f86f46..31a736cf1b 100644
--- a/doc/source/cli/index.rst
+++ b/doc/source/cli/index.rst
@@ -1,5 +1,5 @@
-Command References
-==================
+Administrator Command References
+================================
Here are references for commands not elsewhere documented.
diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
index a5c518d5b2..1c371b556f 100644
--- a/doc/source/configuration/index.rst
+++ b/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>
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 44b85f30ef..c6a8e9516d 100644
--- a/doc/source/index.rst
+++ b/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