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

@@ -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

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

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
+or bifrost, or getting unit tests running can be found here:
-:ref:`dev-quickstart`.
+
+.. 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 <bugs>
   Bug Deputy Guide <bug-deputy>
 
-
+Community and Policies
-Community & Policies
+----------------------
-____________________
 
 .. toctree::
-  :maxdepth: 1
+  :maxdepth: 2
 
   Bare Metal Community <community>
   Developer Contribution Guide <contributing>
@@ -46,12 +54,15 @@ ____________________
   Contributor Vision <vision>
   OpenStack Vision <vision-reflection>
 
+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 <architecture>
   Developing New Notifications <notifications>
@@ -59,21 +70,18 @@ primarily for developers.
   Rolling Upgrades <rolling-upgrades>
   Role Based Access Control Testing <rbac-testing>
 
+Governance and Processes
+------------------------
+
 These pages contain information for PTLs, cross-project liaisons, and core
 reviewers.
 
 .. toctree::
-  :maxdepth: 1
+  :maxdepth: 2
 
   Releasing Ironic Projects <releasing>
   Ironic Governance Structure <governance>
 
-.. 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 <drivers>
-  Writing "vendor_passthru" methods <vendor-passthru>
+  Writing "vendor_passthru" Methods <vendor-passthru>
-  Creating new BIOS interfaces <bios_develop>
+  Creating New BIOS Interfaces <bios_develop>
-  Third party continuous integration testing <third-party-ci>
+  Third Party Continuous Integration Testing <third-party-ci>
   Writing Deploy or Clean Steps <deploy-steps>
 
 Full Ironic Server Python API Reference
 ---------------------------------------
 
 .. toctree::
-  :maxdepth: 1
+  :maxdepth: 2
 
-  api/modules
+  Python Modules Index <api/modules>
 
 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 <jobs-description>
+  Job Roles in the CI <jobs-description>
-  How to add a new job? <adding-new-job>
+  How to Add a New Job? <adding-new-job>
-  How to debug failures in CI jobs <debug-ci-failures>
+  How to Debug Failures in CI Jobs <debug-ci-failures>

doc/source/index.rst

@@ -93,7 +93,7 @@ Contributor Guide
 =================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    contributor/index