Documentation reorg

Reorganizing docs as recommended in:

https://www.divio.com/blog/documentation/

This is simply a reorganization of the existing documents and changes
no content EXCEPT to correct the location of sphinx doc references.
Expect followup changes to change document names (to reflect the new
structure) and to move content from existing guides (e.g., to move the
pipeline/project/job structure definitions out of the "Project Configuration"
reference guide into their own reference documents for easier locatability).

All documents are now located in either the "overview", "tutorials",
"discussions", or "references" subdirectories to reflect the new structure
presented to the user. Code examples and images are moved to "examples" and
"images" root-level directories.

Developer specific documents are located in the "references/developer"
directory.

Change-Id: I538ffd7409941c53bf42fe64b7acbc146023c1e3

doc/source/admin/index.rst

@@ -1,23 +0,0 @@
-Administrator's Guide
-=====================
-
-This guide is intended for administrators of Zuul systems.  It covers
-installation, operation, and the portion of Zuul configuration that
-occurs outside of the projects upon which Zuul operates.  Advanced
-users may be interested in some of the concepts described here, as
-well as understanding what features the underlying configuration
-provides to in-project configuration.
-
-.. toctree::
-   :maxdepth: 2
-
-   quick-start
-   installation
-   zuul-from-scratch
-   components
-   connections
-   tenants
-   monitoring
-   client
-   tenant-scoped-rest-api
-   troubleshooting

doc/source/discussions/index.rst

@@ -1,5 +1,5 @@
-User's Guide
+Discussions
-============
+===========
 
 This guide is for all users of Zuul.  If you work on a project where
 Zuul is used to drive automation (whether that's testing proposed
@@ -12,12 +12,8 @@ configure it to meet your needs.
    :maxdepth: 2
 
    concepts
+   components
    gating
-   config
+   tenants
-   jobs
    encryption
-   web
+   tenant-scoped-rest-api
-   client-user
-   badges
-   howtos
-   vulnerabilities

doc/source/howtos/admins/index.rst

@@ -0,0 +1,9 @@
+Admin How-to Guides
+===================
+
+.. toctree::
+   :maxdepth: 1
+
+   installation
+   zuul-from-scratch
+   troubleshooting

doc/source/howtos/users/index.rst

@@ -0,0 +1,9 @@
+User How-to Guides
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   cross-project-gating
+   pti
+   badges

doc/source/index.rst

@@ -5,13 +5,6 @@ Zuul is a program that drives continuous integration, delivery, and
 deployment systems with a focus on project gating and interrelated
 projects.
 
-Zuul's documentation is organized in three guides based on audience.
-If Zuul is being used to gate or drive automation around your project,
-read the :doc:`user/index` to find out how to configure Zuul.  If you
-are installing or operating a Zuul system, you will also find the
-:doc:`admin/index` useful.  If you want help make Zuul itself better,
-take a look at the :doc:`developer/index`.
-
 If you are looking for the Edge routing service named Zuul that is
 related to Netflix, it can be found here:
 https://github.com/Netflix/zuul
@@ -20,30 +13,56 @@ If you are looking for the Javascript testing tool named Zuul, it
 can be found here:
 https://github.com/defunctzombie/zuul
 
-Contents:
+.. toctree::
+   :maxdepth: 2
+
+   overview/index
+
+Documentation
+-------------
+
+Zuul Users
+**********
 
 .. toctree::
    :maxdepth: 2
 
-   user/index
+   tutorials/users/index
-   admin/index
-   developer/index
-   releasenotes
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
-   governance
+   howtos/users/index
+
+Zuul Admins
+***********
 
 .. toctree::
-   :hidden:
+   :maxdepth: 2
 
-   glossary
+   tutorials/admins/index
+
+.. toctree::
+   :maxdepth: 2
+
+   howtos/admins/index
+
+Digging Deeper
+**************
+
+.. toctree::
+   :maxdepth: 2
+
+   discussions/index
+
+.. toctree::
+   :maxdepth: 2
+
+   references/index
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`search`
-* :ref:`glossary`
 

doc/source/overview/index.rst

@@ -0,0 +1,9 @@
+Overview
+========
+
+.. toctree::
+   :maxdepth: 2
+
+   governance
+   vulnerabilities
+   releasenotes

doc/source/overview/releasenotes.rst

@@ -1,4 +1,3 @@
-=============
 Release Notes
 =============
 

doc/source/references/config.rst

@@ -184,7 +184,7 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
          appear in the repository when merged.
 
          For more detail on the theory and operation of Zuul's
-         dependent pipeline manager, see: :doc:`gating`.
+         dependent pipeline manager, see: :doc:`/discussions/gating`.
 
       .. value:: supercedent