From 656f93b6e7a066c9a91150ecdd96ded4e6fad792 Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur 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 + 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 + Deployment + Cleaning + Adoption + Retirement + RAID Configuration + BIOS Settings + Firmware Updates + Node Rescuing + Booting from Volume + Configuring Web or Serial Console + Enabling Notifications + Node Multi-Tenancy + Booting a Ramdisk or an ISO + Hardware Burn-in + Vendor Passthru + Servicing + Windows Images + Deploying without BMC Credentials + Layer 3 or DHCP-less Ramdisk Booting + Deploying with Anaconda 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 - Node Hardware Inspection - Node Deployment - Node Cleaning - Node Adoption - Node Retirement - RAID Configuration - BIOS Settings - Firmware Updates - Node Rescuing - Configuring to boot from volume - Multi-tenant Networking - Port Groups - Configuring Web or Serial Console - Enabling Notifications - Conductor Groups - Upgrade Guide - Security - Troubleshooting FAQ - Power Synchronization - Node Multi-Tenancy - Fast-Track Deployment - Booting a Ramdisk or an ISO - Hardware Burn-in - Vendor Passthru - Servicing - Authentication Support for Instance Images - -Drivers, Hardware Types and Hardware Interfaces ------------------------------------------------ - .. toctree:: :maxdepth: 3 drivers - -Advanced Topics ---------------- - -.. toctree:: - :maxdepth: 1 - - Ceph Object Gateway - Windows Images - Emitting Software Metrics - Auditing API Traffic - Service State Reporting - Agent Token - Deploying without BMC Credentials - Layer 3 or DHCP-less Ramdisk Booting - Tuning Ironic - Role Based Access Control - Deploying with Anaconda - Steps - 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 + Multi-tenant Networking + Port Groups + Conductor Groups + Security + Troubleshooting FAQ + Power Synchronization + Fast-Track Deployment + Authentication for Instance Images + OVN Networking + Ceph Object Gateway + Emitting Software Metrics + Auditing API Traffic + Service State Reporting + Tuning Ironic + Role Based Access Control + Dashboard Integration + 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 Policies 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 + API Reference (latest) + API 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 - API Reference (latest) - API Version History - -Command References -================== - -Here are references for commands not elsewhere documented. - .. toctree:: :maxdepth: 2 - cli/index + admin/architecture + +* `Release Notes `_ + +.. toctree:: + :hidden: + + admin/index Contributor Guide ================= @@ -97,11 +99,6 @@ Contributor Guide contributor/index -Release Notes -============= - -`Release Notes `_ - .. only:: html Indices and tables