doc: Create directory structure for docs migration

The spec [1] recommends the following sections:

- install
- contributor
- configuration
- cli
- admin
- user
- reference

Only a few of these are useful here:

- contributor
- cli
- user
- reference

Add these and populate them.

[1] specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration

Change-Id: I8a9ddcc915f25ebfaa1e994dba6c15883bd2715d

14 files changed, 195 insertions, 229 deletions

diff --git a/.gitignore b/.gitignore
index 372efb94..82ede6ad 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,5 +18,9 @@ novaclient/versioninfo
 *egg-info
 .eggs
 
+# Files created by documentation build
+/doc/build/
+/doc/source/reference/api/
+
 # Files created by releasenotes build
-releasenotes/build
+/releasenotes/build
diff --git a/README.rst b/README.rst
index 0be65d77..00f86f46 100644
--- a/README.rst
+++ b/README.rst
@@ -7,8 +7,9 @@ Team and repository tags
 
 .. Change things from this point on
 
-Python bindings to the OpenStack Nova API
-=========================================
+============================================
+Python bindings to the OpenStack Compute API
+============================================
 
 .. image:: https://img.shields.io/pypi/v/python-novaclient.svg
     :target: https://pypi.python.org/pypi/python-novaclient/
@@ -18,23 +19,14 @@ Python bindings to the OpenStack Nova API
     :target: https://pypi.python.org/pypi/python-novaclient/
     :alt: Downloads
 
-This is a client for the OpenStack Nova API. There's a Python API (the
-``novaclient`` module), and a command-line script (``nova``). Each
-implements 100% of the OpenStack Nova API.
-
-See the `OpenStack CLI guide`_ for information on how to use the ``nova``
-command-line tool. You may also want to look at the
-`OpenStack API documentation`_.
-
-.. _OpenStack CLI Guide: http://docs.openstack.org/cli-reference/nova.html
-.. _OpenStack API documentation: http://developer.openstack.org/api-ref-compute-v2.1.html
-
-python-novaclient is licensed under the Apache License like the rest of
-OpenStack.
+This is a client for the OpenStack Compute API. It provides a Python API (the
+``novaclient`` module) and a command-line script (``nova``). Each implements
+100% of the OpenStack Compute API.
 
 * License: Apache License, Version 2.0
 * `PyPi`_ - package installation
 * `Online Documentation`_
+* `Launchpad project`_ - release management
 * `Blueprints`_ - feature specifications
 * `Bugs`_ - issue tracking
 * `Source`_
@@ -42,86 +34,10 @@ OpenStack.
 * `How to Contribute`_
 
 .. _PyPi: https://pypi.python.org/pypi/python-novaclient
-.. _Online Documentation: http://docs.openstack.org/developer/python-novaclient
+.. _Online Documentation: http://docs.openstack.org/python-novaclient
+.. _Launchpad project: https://launchpad.net/python-novaclient
 .. _Blueprints: https://blueprints.launchpad.net/python-novaclient
 .. _Bugs: https://bugs.launchpad.net/python-novaclient
 .. _Source: https://git.openstack.org/cgit/openstack/python-novaclient
 .. _How to Contribute: http://docs.openstack.org/infra/manual/developers.html
 .. _Specs: http://specs.openstack.org/openstack/nova-specs/
-
-
-.. contents:: Contents:
-   :local:
-
-Command-line API
-----------------
-
-Installing this package gets you a shell command, ``nova``, that you
-can use to interact with any OpenStack cloud.
-
-You'll need to provide your OpenStack username and password. You can do this
-with the ``--os-username``, ``--os-password`` and  ``--os-project-name``
-params, but it's easier to just set them as environment variables::
-
-    export OS_USERNAME=<username>
-    export OS_PASSWORD=<password>
-    export OS_PROJECT_NAME=<project-name>
-
-
-You will also need to define the authentication url with ``--os-auth-url``
-and the version of the API with ``--os-compute-api-version``.  Or set them as
-environment variables as well and set the OS_AUTH_URL to the keystone endpoint::
-
-    export OS_AUTH_URL=http://<url-to-openstack-keystone>:5000/v3/
-    export OS_COMPUTE_API_VERSION=2.1
-
-
-Since Keystone can return multiple regions in the Service Catalog, you
-can specify the one you want with ``--os-region-name`` (or
-``export OS_REGION_NAME``). It defaults to the first in the list returned.
-
-You'll find complete documentation on the shell by running
-``nova help``
-
-Python API
-----------
-
-There's also a complete Python API, with documentation linked below.
-
-
-To use with keystone as the authentication system::
-
-    >>> from keystoneauth1.identity import v3
-    >>> from keystoneauth1 import session
-    >>> from novaclient import client
-    >>> auth = v3.Password(auth_url='http://example.com:5000/v3',
-    ...                    username='username',
-    ...                    password='password',
-    ...                    project_name='project-name',
-    ...                    user_domain_id='default',
-    ...                    project_domain_id='default')
-    >>> sess = session.Session(auth=auth)
-    >>> nova = client.Client("2.1", session=sess)
-    >>> nova.flavors.list()
-    [...]
-    >>> nova.servers.list()
-    [...]
-    >>> nova.keypairs.list()
-    [...]
-
-
-Testing
--------
-
-There are multiple test targets that can be run to validate the code.
-
-* tox -e pep8 - style guidelines enforcement
-* tox -e py27 - traditional unit testing
-* tox -e functional - live functional testing against an existing
-  openstack
-
-Functional testing assumes the existence of a `clouds.yaml` file as supported
-by `os-client-config` (http://docs.openstack.org/developer/os-client-config)
-It assumes the existence of a cloud named `devstack` that behaves like a normal
-devstack installation with a demo and an admin user/tenant - or clouds named
-`functional_admin` and `functional_nonadmin`.
diff --git a/doc/.gitignore b/doc/.gitignore
deleted file mode 100644
index 8e0be80f..00000000
--- a/doc/.gitignore
+++ /dev/null
@@ -1,2 +0,0 @@
-build/
-source/ref/
diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
new file mode 100644
index 00000000..ce291731
--- /dev/null
+++ b/doc/source/cli/index.rst
@@ -0,0 +1,8 @@
+===============
+ CLI Reference
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   nova
diff --git a/doc/source/man/nova.rst b/doc/source/cli/nova.rst
index 56e56b59..c3c6caf4 100644
--- a/doc/source/man/nova.rst
+++ b/doc/source/cli/nova.rst
@@ -1,6 +1,6 @@
-====
-nova
-====
+======
+ nova
+======
 
 
 SYNOPSIS
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 4813effb..19d10bde 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -22,37 +22,46 @@ sys.path.insert(0, ROOT)
 sys.path.insert(0, BASE_DIR)
 
 
+# TODO(stephenfin): This looks like something that pbr's autodoc integration
+# could be doing for us. Investigate.
+
 def gen_ref(ver, title, names):
-    refdir = os.path.join(BASE_DIR, "ref")
+    refdir = os.path.join(BASE_DIR, "reference", "api")
     pkg = "novaclient"
     if ver:
         pkg = "%s.%s" % (pkg, ver)
         refdir = os.path.join(refdir, ver)
     if not os.path.exists(refdir):
         os.makedirs(refdir)
-    idxpath = os.path.join(refdir, "index.rst")
-    with open(idxpath, "w") as idx:
-        idx.write(("%(title)s\n"
-                   "%(signs)s\n"
-                   "\n"
-                   ".. toctree::\n"
-                   "   :maxdepth: 1\n"
-                   "\n") % {"title": title, "signs": "=" * len(title)})
-        for name in names:
-            idx.write("   %s\n" % name)
-            rstpath = os.path.join(refdir, "%s.rst" % name)
-            with open(rstpath, "w") as rst:
-                rst.write(("%(title)s\n"
-                           "%(signs)s\n"
-                           "\n"
-                           ".. automodule:: %(pkg)s.%(name)s\n"
-                           "   :members:\n"
-                           "   :undoc-members:\n"
-                           "   :show-inheritance:\n"
-                           "   :noindex:\n")
-                          % {"title": name.capitalize(),
-                             "signs": "=" * len(name),
-                             "pkg": pkg, "name": name})
+
+    # we don't want to write index files for top-level directories - only
+    # sub-directories
+    if ver:
+        idxpath = os.path.join(refdir, "index.rst")
+        with open(idxpath, "w") as idx:
+            idx.write(("%(title)s\n"
+                       "%(signs)s\n"
+                       "\n"
+                       ".. toctree::\n"
+                       "   :maxdepth: 1\n"
+                       "\n") % {"title": title, "signs": "=" * len(title)})
+            for name in names:
+                idx.write("   %s\n" % name)
+
+    for name in names:
+        rstpath = os.path.join(refdir, "%s.rst" % name)
+        with open(rstpath, "w") as rst:
+            rst.write(("%(title)s\n"
+                       "%(signs)s\n"
+                       "\n"
+                       ".. automodule:: %(pkg)s.%(name)s\n"
+                       "   :members:\n"
+                       "   :undoc-members:\n"
+                       "   :show-inheritance:\n"
+                       "   :noindex:\n")
+                      % {"title": name.capitalize(),
+                         "signs": "=" * len(name),
+                         "pkg": pkg, "name": name})
 
 
 def get_module_names():
@@ -107,14 +116,11 @@ pygments_style = 'sphinx'
 # Sphinx are currently 'default' and 'sphinxdoc'.
 html_theme = 'default'
 
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'python-novaclientdoc'
-
 # -- Options for manual page output ------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('man/nova', 'nova', 'OpenStack Nova command line client',
+    ('cli/nova', 'nova', 'OpenStack Nova command line client',
      ['OpenStack Contributors'], 1),
 ]
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
new file mode 100644
index 00000000..cf8dccae
--- /dev/null
+++ b/doc/source/contributor/index.rst
@@ -0,0 +1,16 @@
+===================
+ Contributor Guide
+===================
+
+Code is hosted at `git.openstack.org`__. Submit bugs to the Nova project on
+`Launchpad`__. Submit code to the `openstack/python-novaclient` project using
+`Gerrit`__.
+
+__ https://git.openstack.org/cgit/openstack/python-novaclient
+__ https://launchpad.net/nova
+__ http://docs.openstack.org/infra/manual/developers.html#development-workflow
+
+.. toctree::
+   :maxdepth: 2
+
+   testing
diff --git a/doc/source/contributor/testing.rst b/doc/source/contributor/testing.rst
new file mode 100644
index 00000000..c4e59143
--- /dev/null
+++ b/doc/source/contributor/testing.rst
@@ -0,0 +1,28 @@
+=========
+ Testing
+=========
+
+The preferred way to run the unit tests is using ``tox``. There are multiple
+test targets that can be run to validate the code.
+
+``tox -e pep8``
+
+  Style guidelines enforcement.
+
+``tox -e py27``
+
+  Traditional unit testing.
+
+``tox -e functional``
+
+  Live functional testing against an existing OpenStack instance.
+
+Functional testing assumes the existence of a `clouds.yaml` file as supported
+by `os-client-config <http://docs.openstack.org/developer/os-client-config>`__
+It assumes the existence of a cloud named `devstack` that behaves like a normal
+DevStack installation with a demo and an admin user/tenant - or clouds named
+`functional_admin` and `functional_nonadmin`.
+
+Refer to  `Consistent Testing Interface`__ for more details.
+
+__ http://git.openstack.org/cgit/openstack/governance/tree/reference/project-testing-interface.rst
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 4421c910..4ee0122c 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,13 +1,14 @@
-Python bindings to the OpenStack Nova API
-=========================================
+===========================================
+ Python bindings to the OpenStack Nova API
+===========================================
 
 This is a client for OpenStack Nova API. There's :doc:`a Python API
-<api>` (the :mod:`novaclient` module), and a :doc:`command-line script
-<shell>` (installed as :program:`nova`). Each implements the entire
-OpenStack Nova API.
+<reference/api/index>` (the :mod:`novaclient` module), and a :doc:`command-line
+script </user/shell>` (installed as :program:`nova`). Each implements the
+entire OpenStack Nova API.
 
-You'll need credentials for an OpenStack cloud that implements the
-Compute API, such as TryStack, HP, or Rackspace, in order to use the nova client.
+You'll need credentials for an OpenStack cloud that implements the Compute API,
+such as TryStack, HP, or Rackspace, in order to use the nova client.
 
 .. seealso::
 
@@ -17,83 +18,10 @@ Compute API, such as TryStack, HP, or Rackspace, in order to use the nova client
 
     __ https://developer.openstack.org/api-guide/compute/index.html
 
-Contents:
-
 .. toctree::
    :maxdepth: 2
 
-   shell
-   api
-   ref/index
-   ref/v2/index
-
-Contributing
-============
-
-Code is hosted at `git.openstack.org`_. Submit bugs to the Nova project on
-`Launchpad`_. Submit code to the openstack/python-novaclient project using
-`Gerrit`_.
-
-.. _git.openstack.org: https://git.openstack.org/cgit/openstack/python-novaclient
-.. _Launchpad: https://launchpad.net/nova
-.. _Gerrit: http://docs.openstack.org/infra/manual/developers.html#development-workflow
-
-Testing
--------
-
-The preferred way to run the unit tests is using ``tox``.
-
-See `Consistent Testing Interface`_ for more details.
-
-.. _Consistent Testing Interface: http://git.openstack.org/cgit/openstack/governance/tree/reference/project-testing-interface.rst
-
-Deprecating commands
-====================
-
-There are times when commands need to be deprecated due to rename or removal.
-The process for command deprecation is:
-
-  1. Push up a change for review which deprecates the command(s).
-
-   - The change should print a deprecation warning to stderr each time a
-     deprecated command is used.
-   - That warning message should include a rough timeline for when the command
-     will be removed and what should be used instead, if anything.
-   - The description in the help text for the deprecated command should mark
-     that it is deprecated.
-   - The change should include a release note with the ``deprecations`` section
-     filled out.
-   - The deprecation cycle is typically the first client release *after* the
-     next *full* Nova server release so that there is at least six months of
-     deprecation.
-
-  2. Once the change is approved, have a member of the `nova-release`_ team
-     release a new version of python-novaclient.
-
-     .. _nova-release: https://review.openstack.org/#/admin/groups/147,members
-
-  3. Example: `<https://review.openstack.org/#/c/185141/>`_
-
-     This change was made while the Nova 12.0.0 Liberty release was in
-     development. The current version of python-novaclient at the time was
-     2.25.0. Once the change was merged, python-novaclient 2.26.0 was released.
-     Since there was less than six months before 12.0.0 would be released, the
-     deprecation cycle ran through the 13.0.0 Nova server release.
-
-
-Man Page
-========
-
-.. toctree::
-   :maxdepth: 1
-
-   man/nova
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   user/index
+   reference/index
+   cli/index
+   contributor/index
diff --git a/doc/source/api.rst b/doc/source/reference/api/index.rst
index 450d66d9..c5ed6d88 100644
--- a/doc/source/api.rst
+++ b/doc/source/reference/api/index.rst
@@ -1,5 +1,6 @@
-The :mod:`novaclient` Python API
-================================
+==================================
+ The :mod:`novaclient` Python API
+==================================
 
 .. module:: novaclient
    :synopsis: A client for the OpenStack Nova API.
@@ -18,7 +19,6 @@ Here ``VERSION`` can be a string or ``novaclient.api_versions.APIVersion`` obj.
 If you prefer string value, you can use ``1.1`` (deprecated now), ``2`` or
 ``2.X`` (where X is a microversion).
 
-
 Alternatively, you can create a client instance using the keystoneauth
 session API::
 
@@ -98,7 +98,6 @@ Then call methods on its managers::
 
 .. _1493576: https://launchpad.net/bugs/1493576
 
-
 Reference
 ---------
 
@@ -107,5 +106,5 @@ For more information, see the reference:
 .. toctree::
    :maxdepth: 2
 
-   ref/index
-   ref/v2/index
+   v2/index
+   exceptions
diff --git a/doc/source/reference/deprecation-policy.rst b/doc/source/reference/deprecation-policy.rst
new file mode 100644
index 00000000..0085bca9
--- /dev/null
+++ b/doc/source/reference/deprecation-policy.rst
@@ -0,0 +1,32 @@
+Deprecating commands
+====================
+
+There are times when commands need to be deprecated due to rename or removal.
+The process for command deprecation is:
+
+1. Push up a change for review which deprecates the command(s).
+
+   - The change should print a deprecation warning to ``stderr`` each time a
+     deprecated command is used.
+   - That warning message should include a rough timeline for when the command
+     will be removed and what should be used instead, if anything.
+   - The description in the help text for the deprecated command should mark
+     that it is deprecated.
+   - The change should include a release note with the ``deprecations`` section
+     filled out.
+   - The deprecation cycle is typically the first client release *after* the
+     next *full* nova server release so that there is at least six months of
+     deprecation.
+
+2. Once the change is approved, have a member of the `nova-release`_ team
+   release a new version of `python-novaclient`.
+
+   .. _nova-release: https://review.openstack.org/#/admin/groups/147,members
+
+3. Example: `<https://review.openstack.org/#/c/185141/>`_
+
+   This change was made while the nova 12.0.0 Liberty release was in
+   development. The current version of `python-novaclient` at the time was
+   2.25.0. Once the change was merged, `python-novaclient` 2.26.0 was released.
+   Since there was less than six months before 12.0.0 would be released, the
+   deprecation cycle ran through the 13.0.0 nova server release.
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
new file mode 100644
index 00000000..92e93855
--- /dev/null
+++ b/doc/source/reference/index.rst
@@ -0,0 +1,8 @@
+Reference
+=========
+
+.. toctree::
+   :maxdepth: 1
+
+   api/index
+   deprecation-policy
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
new file mode 100644
index 00000000..3c54920b
--- /dev/null
+++ b/doc/source/user/index.rst
@@ -0,0 +1,8 @@
+============
+ User Guide
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   shell
diff --git a/doc/source/shell.rst b/doc/source/user/shell.rst
index 6f72c3a3..b2d7d9ef 100644
--- a/doc/source/shell.rst
+++ b/doc/source/user/shell.rst
@@ -1,19 +1,20 @@
-The :program:`nova` shell utility
-=================================
+===================================
+ The :program:`nova` Shell Utility
+===================================
 
 .. program:: nova
 .. highlight:: bash
 
-The :program:`nova` shell utility interacts with OpenStack Nova API
-from the command line. It supports the entirety of the OpenStack Nova API.
+The :program:`nova` shell utility interacts with OpenStack Nova API from the
+command line. It supports the entirety of the OpenStack Nova API.
 
-First, you'll need an OpenStack Nova account and an API key. You get this
-by using the `nova-manage` command in OpenStack Nova.
+First, you'll need an OpenStack Nova account and an API key. You get this by
+using the `nova-manage` command in OpenStack Nova.
 
 You'll need to provide :program:`nova` with your OpenStack username and API
 key. You can do this with the `--os-username`, `--os-password` and
 `--os-tenant-id` options, but it's easier to just set them as environment
-variables by setting two environment variables:
+variables by setting some environment variables:
 
 .. envvar:: OS_USERNAME
 
@@ -35,18 +36,32 @@ variables by setting two environment variables:
 
     The OpenStack API version.
 
+.. envvar:: OS_REGION_NAME
+
+    The Keystone region name. Defaults to the first region if multiple regions
+    are available.
+
 For example, in Bash you'd use::
 
     export OS_USERNAME=yourname
     export OS_PASSWORD=yadayadayada
     export OS_TENANT_NAME=myproject
-    export OS_AUTH_URL=http://...
-    export OS_COMPUTE_API_VERSION=2
+    export OS_AUTH_URL=http://<url-to-openstack-keystone>:5000/v3/
+    export OS_COMPUTE_API_VERSION=2.1
 
 From there, all shell commands take the form::
 
     nova <command> [arguments...]
 
-Run :program:`nova help` to get a full list of all possible commands,
-and run :program:`nova help <command>` to get detailed help for that
-command.
+Run :program:`nova help` to get a full list of all possible commands, and run
+:program:`nova help <command>` to get detailed help for that command.
+
+Reference
+---------
+
+For more information, see the reference:
+
+.. toctree::
+   :maxdepth: 2
+
+   /cli/nova