From a36fd00951f42057a06f1cf09db9e02ed1e8354a Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur Date: Mon, 24 Jun 2024 13:12:54 +0200 Subject: [PATCH] Rework the navigation in the contributor guide The goal here is to give newcomers an easier overview of the contributor guide. Currently, the index page only points at a couple of sections in the contributor index, which may be confusing. So: 1) Expand the contributor reference from the index page one more level. 2) Update headings in the contributor guide to match the toctrees and their expected level. 3) Expand toctrees in the contributor index one more level. 4) Move references to the development enviroment to a higher level toctree to make them visible in the index. 5) Apply consistent upper case heading. Change-Id: Ifb9fdc96b368095437771217090120e83eaa0fa7 --- doc/source/contributor/bifrost-dev-guide.rst | 6 +- doc/source/contributor/dev-quickstart.rst | 7 --- doc/source/contributor/index.rst | 64 +++++++++++--------- doc/source/index.rst | 2 +- 4 files changed, 40 insertions(+), 39 deletions(-) diff --git a/doc/source/contributor/bifrost-dev-guide.rst b/doc/source/contributor/bifrost-dev-guide.rst index 68db44e98c..8dc3da7f60 100644 --- a/doc/source/contributor/bifrost-dev-guide.rst +++ b/doc/source/contributor/bifrost-dev-guide.rst @@ -1,6 +1,6 @@ -===================================== -Bifrost Development Environment Guide -===================================== +=============================== +Bifrost Development Environment +=============================== Bifrost is a project that deploys and operates Ironic using ansible. It is generally used standalone, without many other services running alongside. This diff --git a/doc/source/contributor/dev-quickstart.rst b/doc/source/contributor/dev-quickstart.rst index aeb9281888..922a8981c5 100644 --- a/doc/source/contributor/dev-quickstart.rst +++ b/doc/source/contributor/dev-quickstart.rst @@ -38,13 +38,6 @@ tox environments before pushing code as an extra check. More information about running tests in tox available in :ref:`unit`. -.. toctree:: - :hidden: - - devstack-guide - bifrost-dev-guide - local-dev-guide - .. _integrated: Integrated Testing Environments diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 79b7701f31..35cd80a68f 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -15,29 +15,37 @@ It will also be helpful to be familiar with which contains basic information about how to use many of the community tools and OpenStack practices. -Basics -______ - Basic information about setting up development environments with devstack -or bifrost, or getting unit tests running can be found in our -:ref:`dev-quickstart`. +or bifrost, or getting unit tests running can be found here: + +.. toctree:: + :maxdepth: 2 + + dev-quickstart + devstack-guide + bifrost-dev-guide + local-dev-guide + +.. toctree:: + :hidden: + + states Bugs ---- Information about how ironic projects handle bugs can be found below. .. toctree:: - :maxdepth: 1 + :maxdepth: 2 Bugs Reporting and Triaging Guide Bug Deputy Guide - -Community & Policies -____________________ +Community and Policies +---------------------- .. toctree:: - :maxdepth: 1 + :maxdepth: 2 Bare Metal Community Developer Contribution Guide @@ -46,12 +54,15 @@ ____________________ Contributor Vision OpenStack Vision +Architecture and Implementation Details +--------------------------------------- + The following pages describe the architecture of the Bare Metal service and may be helpful to anyone working on or with the service, but are written primarily for developers. .. toctree:: - :maxdepth: 1 + :maxdepth: 2 Ironic System Architecture Developing New Notifications @@ -59,21 +70,18 @@ primarily for developers. Rolling Upgrades Role Based Access Control Testing +Governance and Processes +------------------------ + These pages contain information for PTLs, cross-project liaisons, and core reviewers. .. toctree:: - :maxdepth: 1 + :maxdepth: 2 Releasing Ironic Projects Ironic Governance Structure -.. toctree:: - :hidden: - - states - dev-quickstart - Writing Drivers --------------- @@ -92,21 +100,21 @@ this are provided below. Driver authors are strongly encouraged to talk with the developer community about any implementation using this functionality. .. toctree:: - :maxdepth: 1 + :maxdepth: 2 Driver Overview - Writing "vendor_passthru" methods - Creating new BIOS interfaces - Third party continuous integration testing + Writing "vendor_passthru" Methods + Creating New BIOS Interfaces + Third Party Continuous Integration Testing Writing Deploy or Clean Steps Full Ironic Server Python API Reference --------------------------------------- .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - api/modules + Python Modules Index Understanding the Ironic's CI ----------------------------- @@ -116,8 +124,8 @@ and how to debug failures that may arise. To facilitate that, we have created the documentation below. .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - Job roles in the CI - How to add a new job? - How to debug failures in CI jobs + Job Roles in the CI + How to Add a New Job? + How to Debug Failures in CI Jobs diff --git a/doc/source/index.rst b/doc/source/index.rst index 8d37020381..44b85f30ef 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -93,7 +93,7 @@ Contributor Guide ================= .. toctree:: - :maxdepth: 2 + :maxdepth: 3 contributor/index