From b9efc9d641f26456805d24a5eba90356a9c9b4aa Mon Sep 17 00:00:00 2001
From: Sean Dague <sean@dague.net>
Date: Fri, 4 Aug 2017 13:18:41 -0400
Subject: [PATCH] Create reference subpage

In an attempt to make the main navigation sidebar not be visual mud
(and really confusing) create a reference sub page that explains all
the references.

Part of bp: doc-migration

Change-Id: I005fc24e49487631d7fe73cb498c61619bcaac9d
---
 doc/source/contributor/index.rst |  1 +
 doc/source/index.rst             | 44 ++++++++++++++++--------------
 doc/source/reference/index.rst   | 46 ++++++++++++++++++++++++++++++++
 3 files changed, 71 insertions(+), 20 deletions(-)
 create mode 100644 doc/source/reference/index.rst

diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
index cfb399e08d..8fc84eeeb0 100644
--- a/doc/source/contributor/index.rst
+++ b/doc/source/contributor/index.rst
@@ -47,6 +47,7 @@ For Reviewers
 * :doc:`/contributor/code-review`: important cheat sheet for what's important
   when doing code review in Nova, especially some things that are hard to test
   for, but need human eyes.
+* :doc:`/reference/i18n`: what we require for i18n in patches
 
 Testing
 =======
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 3288adc142..e8be6668e7 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -88,8 +88,8 @@ integration testing efforts.
    user/feature-classification
    user/support-matrix
 
-Developer Guide
-===============
+For Contributors
+================
 
 If you are new to Nova, this should help you start to understand what Nova
 actually does, and why.
@@ -99,6 +99,15 @@ actually does, and why.
 
    contributor/index
 
+There are also a number of technical references on both current and future
+looking parts of our architecture. These are collected below.
+
+.. toctree::
+   :maxdepth: 1
+
+   reference/index
+
+
 Architecture Concepts
 ----------------------
 
@@ -115,18 +124,13 @@ Open Development.
 .. toctree::
    :maxdepth: 1
 
-   reference/rpc
    user/architecture
    user/block-device-mapping
    user/conductor
    user/filter-scheduler
    user/aggregates
-   reference/i18n
-   reference/notifications
    user/placement
    user/quotas
-   reference/threading
-   reference/vm-states
    user/wsgi
 
 Architecture Evolution Plans
@@ -142,12 +146,8 @@ these are a great place to start reading up on the current plans.
 .. toctree::
    :maxdepth: 1
 
-   user/cells
    user/cellsv2_layout
    user/upgrade
-   reference/policy-enforcement
-   reference/stable-api
-   reference/scheduler-evolution
 
 Configuration
 -------------
@@ -175,13 +175,6 @@ Man Pages
 
    cli/index
 
-Module Reference
-----------------
-.. toctree::
-   :maxdepth: 1
-
-   reference/services
-
 
 .. # NOTE(mriedem): This is the section where we hide things that we don't
    # actually want in the table of contents but sphinx build would fail if
@@ -191,7 +184,6 @@ Module Reference
    :hidden:
 
    contributor/development-environment
-   reference/gmr
    contributor/api
    contributor/api-2
    contributor/blueprints
@@ -207,6 +199,18 @@ Module Reference
    contributor/how-to-get-involved
    contributor/process
    contributor/project-scope
+   user/cells
+   reference/gmr
+   reference/i18n
+   reference/notifications
+   reference/policy-enforcement
+   reference/rpc
+   reference/scheduler-evolution
+   reference/services
+   reference/stable-api
+   reference/threading
+   reference/vm-states
+   reference/i18n
 
 Installation Guide
 ==================
@@ -224,7 +228,7 @@ Metadata
 
     user/vendordata
 
-Administrators Guide
+Administration Guide
 ====================
 .. toctree::
    :maxdepth: 2
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
new file mode 100644
index 0000000000..cee5c8f2b3
--- /dev/null
+++ b/doc/source/reference/index.rst
@@ -0,0 +1,46 @@
+================================
+ Technical Reference Deep Dives
+================================
+
+The nova project is large, and there are lots of complicated parts in it where
+it helps to have an overview to understand how the internals of a particular
+part work.
+
+Internals
+=========
+
+The following is a dive into some of the internals in nova.
+
+* :doc:`/reference/rpc`: How nova uses AMQP as an RPC transport
+* :doc:`/reference/services`: Module descriptions for some of the key modules
+  used in starting / running services
+* :doc:`/reference/vm-states`: Cheat sheet for understanding the life cycle of
+  compute instances
+* :doc:`/reference/threading`: The concurrency model used in nova, which is
+  based on eventlet, and may not be familiar to everyone.
+* :doc:`/reference/notifications`: How the notifications subsystem works in
+  nova, and considerations when adding notifications.
+
+Debugging
+=========
+
+* :doc:`/reference/gmr`: Inspired by Amiga, a way to trigger a very
+  comprehensive dump of a running service for deep debugging.
+
+Forward Looking Plans
+=====================
+
+The following section includes documents that describe the overall plan behind
+groups of nova-specs. Most of these cover items relating to the evolution of
+various parts of nova's architecture. Once the work is complete,
+these documents will move into the "Internals" section.
+
+If you want to get involved in shaping the future of nova's architecture,
+these are a great place to start reading up on the current plans.
+
+* :doc:`/user/cells`: Comparison of Cells v1 and v2, and how v2 is evolving
+* :doc:`/reference/policy-enforcement`: How we want policy checks on API actions
+  to work in the future
+* :doc:`/reference/stable-api`: What stable api means to nova
+* :doc:`/reference/scheduler-evolution`: Motivation behind the scheduler /
+  placement evolution