reorganize existing documentation according to the new standard layout

Move existing content around based on the doc-migration specification.

Replace :doc: markup with :ref: to have sphinx keep track of where the
files move and generate valid hyperlinks.

Add a few toctrees and index pages for the new directories.

Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454
Change-Id: I253ee8f89d3ec40e39310c18bb87ed1d3d5de330
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

119 files changed, 78 insertions, 45 deletions

diff --git a/doc/source/authentication.rst b/doc/source/cli/authentication.rst
index be16bd78..5a1d2797 100644
--- a/doc/source/authentication.rst
+++ b/doc/source/cli/authentication.rst
@@ -1,3 +1,5 @@
+.. _authentication:
+
 ==============
 Authentication
 ==============
diff --git a/doc/source/backwards-incompatible.rst b/doc/source/cli/backwards-incompatible.rst
index 033860d3..571d791f 100644
--- a/doc/source/backwards-incompatible.rst
+++ b/doc/source/cli/backwards-incompatible.rst
@@ -10,8 +10,8 @@ Should positional arguments for a command need to change, the OpenStackClient
 team attempts to make the transition as painless as possible. Look for
 deprecation warnings that indicate the new commands (or options) to use.
 
-Commands labeled as a beta according to :doc:`command-beta` are exempt from
-this backwards incompatible change handling.
+Commands labeled as a beta according to :ref:`command-beta` are exempt
+from this backwards incompatible change handling.
 
 Backwards Incompatible Changes
 ==============================
diff --git a/doc/source/command-list.rst b/doc/source/cli/command-list.rst
index c4045b04..9044f693 100644
--- a/doc/source/command-list.rst
+++ b/doc/source/cli/command-list.rst
@@ -1,3 +1,5 @@
+.. _command-list:
+
 ============
 Command List
 ============
diff --git a/doc/source/command-objects/access-token.rst b/doc/source/cli/command-objects/access-token.rst
index b1400412..b1400412 100644
--- a/doc/source/command-objects/access-token.rst
+++ b/doc/source/cli/command-objects/access-token.rst
diff --git a/doc/source/command-objects/address-scope.rst b/doc/source/cli/command-objects/address-scope.rst
index 9155d09e..9155d09e 100644
--- a/doc/source/command-objects/address-scope.rst
+++ b/doc/source/cli/command-objects/address-scope.rst
diff --git a/doc/source/command-objects/aggregate.rst b/doc/source/cli/command-objects/aggregate.rst
index 2029a6c8..2029a6c8 100644
--- a/doc/source/command-objects/aggregate.rst
+++ b/doc/source/cli/command-objects/aggregate.rst
diff --git a/doc/source/command-objects/availability-zone.rst b/doc/source/cli/command-objects/availability-zone.rst
index d4c117a0..d4c117a0 100644
--- a/doc/source/command-objects/availability-zone.rst
+++ b/doc/source/cli/command-objects/availability-zone.rst
diff --git a/doc/source/command-objects/backup.rst b/doc/source/cli/command-objects/backup.rst
index f8923276..f8923276 100644
--- a/doc/source/command-objects/backup.rst
+++ b/doc/source/cli/command-objects/backup.rst
diff --git a/doc/source/command-objects/catalog.rst b/doc/source/cli/command-objects/catalog.rst
index dccf7801..dccf7801 100644
--- a/doc/source/command-objects/catalog.rst
+++ b/doc/source/cli/command-objects/catalog.rst
diff --git a/doc/source/command-objects/command.rst b/doc/source/cli/command-objects/command.rst
index 918fd959..918fd959 100644
--- a/doc/source/command-objects/command.rst
+++ b/doc/source/cli/command-objects/command.rst
diff --git a/doc/source/command-objects/complete.rst b/doc/source/cli/command-objects/complete.rst
index 20e5c41d..20e5c41d 100644
--- a/doc/source/command-objects/complete.rst
+++ b/doc/source/cli/command-objects/complete.rst
diff --git a/doc/source/command-objects/compute-agent.rst b/doc/source/cli/command-objects/compute-agent.rst
index e8317b48..e8317b48 100644
--- a/doc/source/command-objects/compute-agent.rst
+++ b/doc/source/cli/command-objects/compute-agent.rst
diff --git a/doc/source/command-objects/compute-service.rst b/doc/source/cli/command-objects/compute-service.rst
index ba624ea0..ba624ea0 100644
--- a/doc/source/command-objects/compute-service.rst
+++ b/doc/source/cli/command-objects/compute-service.rst
diff --git a/doc/source/command-objects/configuration.rst b/doc/source/cli/command-objects/configuration.rst
index 0e00bbe9..6e704d2d 100644
--- a/doc/source/command-objects/configuration.rst
+++ b/doc/source/cli/command-objects/configuration.rst
@@ -4,6 +4,8 @@ configuration
 
 Available for all services
 
+.. _configuration-show:
+
 configuration show
 ------------------
 
diff --git a/doc/source/command-objects/consistency-group-snapshot.rst b/doc/source/cli/command-objects/consistency-group-snapshot.rst
index 29d50656..29d50656 100644
--- a/doc/source/command-objects/consistency-group-snapshot.rst
+++ b/doc/source/cli/command-objects/consistency-group-snapshot.rst
diff --git a/doc/source/command-objects/consistency-group.rst b/doc/source/cli/command-objects/consistency-group.rst
index 57082c6d..57082c6d 100644
--- a/doc/source/command-objects/consistency-group.rst
+++ b/doc/source/cli/command-objects/consistency-group.rst
diff --git a/doc/source/command-objects/console-log.rst b/doc/source/cli/command-objects/console-log.rst
index bcb23e70..bcb23e70 100644
--- a/doc/source/command-objects/console-log.rst
+++ b/doc/source/cli/command-objects/console-log.rst
diff --git a/doc/source/command-objects/console-url.rst b/doc/source/cli/command-objects/console-url.rst
index 8a5807b6..8a5807b6 100644
--- a/doc/source/command-objects/console-url.rst
+++ b/doc/source/cli/command-objects/console-url.rst
diff --git a/doc/source/command-objects/consumer.rst b/doc/source/cli/command-objects/consumer.rst
index d4ce5dc5..d4ce5dc5 100644
--- a/doc/source/command-objects/consumer.rst
+++ b/doc/source/cli/command-objects/consumer.rst
diff --git a/doc/source/command-objects/container.rst b/doc/source/cli/command-objects/container.rst
index e68955ad..e68955ad 100644
--- a/doc/source/command-objects/container.rst
+++ b/doc/source/cli/command-objects/container.rst
diff --git a/doc/source/command-objects/credential.rst b/doc/source/cli/command-objects/credential.rst
index 0b835c73..0b835c73 100644
--- a/doc/source/command-objects/credential.rst
+++ b/doc/source/cli/command-objects/credential.rst
diff --git a/doc/source/command-objects/domain.rst b/doc/source/cli/command-objects/domain.rst
index 70a3e733..70a3e733 100644
--- a/doc/source/command-objects/domain.rst
+++ b/doc/source/cli/command-objects/domain.rst
diff --git a/doc/source/command-objects/ec2-credentials.rst b/doc/source/cli/command-objects/ec2-credentials.rst
index 9174b041..9174b041 100644
--- a/doc/source/command-objects/ec2-credentials.rst
+++ b/doc/source/cli/command-objects/ec2-credentials.rst
diff --git a/doc/source/command-objects/endpoint.rst b/doc/source/cli/command-objects/endpoint.rst
index 02a75bea..02a75bea 100644
--- a/doc/source/command-objects/endpoint.rst
+++ b/doc/source/cli/command-objects/endpoint.rst
diff --git a/doc/source/command-objects/extension.rst b/doc/source/cli/command-objects/extension.rst
index 36cf418b..36cf418b 100644
--- a/doc/source/command-objects/extension.rst
+++ b/doc/source/cli/command-objects/extension.rst
diff --git a/doc/source/command-objects/federation-protocol.rst b/doc/source/cli/command-objects/federation-protocol.rst
index e1f98174..e1f98174 100644
--- a/doc/source/command-objects/federation-protocol.rst
+++ b/doc/source/cli/command-objects/federation-protocol.rst
diff --git a/doc/source/command-objects/flavor.rst b/doc/source/cli/command-objects/flavor.rst
index 6feb4498..6feb4498 100644
--- a/doc/source/command-objects/flavor.rst
+++ b/doc/source/cli/command-objects/flavor.rst
diff --git a/doc/source/command-objects/floating-ip-pool.rst b/doc/source/cli/command-objects/floating-ip-pool.rst
index 9213b86d..9213b86d 100644
--- a/doc/source/command-objects/floating-ip-pool.rst
+++ b/doc/source/cli/command-objects/floating-ip-pool.rst
diff --git a/doc/source/command-objects/floating-ip.rst b/doc/source/cli/command-objects/floating-ip.rst
index f2f101d3..f2f101d3 100644
--- a/doc/source/command-objects/floating-ip.rst
+++ b/doc/source/cli/command-objects/floating-ip.rst
diff --git a/doc/source/command-objects/group.rst b/doc/source/cli/command-objects/group.rst
index ac938efd..ac938efd 100644
--- a/doc/source/command-objects/group.rst
+++ b/doc/source/cli/command-objects/group.rst
diff --git a/doc/source/command-objects/host.rst b/doc/source/cli/command-objects/host.rst
index cbf34398..cbf34398 100644
--- a/doc/source/command-objects/host.rst
+++ b/doc/source/cli/command-objects/host.rst
diff --git a/doc/source/command-objects/hypervisor-stats.rst b/doc/source/cli/command-objects/hypervisor-stats.rst
index 89faf135..89faf135 100644
--- a/doc/source/command-objects/hypervisor-stats.rst
+++ b/doc/source/cli/command-objects/hypervisor-stats.rst
diff --git a/doc/source/command-objects/hypervisor.rst b/doc/source/cli/command-objects/hypervisor.rst
index 9db384a2..9db384a2 100644
--- a/doc/source/command-objects/hypervisor.rst
+++ b/doc/source/cli/command-objects/hypervisor.rst
diff --git a/doc/source/command-objects/identity-provider.rst b/doc/source/cli/command-objects/identity-provider.rst
index 0c2d02bd..0c2d02bd 100644
--- a/doc/source/command-objects/identity-provider.rst
+++ b/doc/source/cli/command-objects/identity-provider.rst
diff --git a/doc/source/command-objects/image.rst b/doc/source/cli/command-objects/image.rst
index ec51fa93..ec51fa93 100644
--- a/doc/source/command-objects/image.rst
+++ b/doc/source/cli/command-objects/image.rst
diff --git a/doc/source/command-objects/ip-availability.rst b/doc/source/cli/command-objects/ip-availability.rst
index dd39e649..dd39e649 100644
--- a/doc/source/command-objects/ip-availability.rst
+++ b/doc/source/cli/command-objects/ip-availability.rst
diff --git a/doc/source/command-objects/ip-fixed.rst b/doc/source/cli/command-objects/ip-fixed.rst
index f5b11dc6..f5b11dc6 100644
--- a/doc/source/command-objects/ip-fixed.rst
+++ b/doc/source/cli/command-objects/ip-fixed.rst
diff --git a/doc/source/command-objects/ip-floating-pool.rst b/doc/source/cli/command-objects/ip-floating-pool.rst
index 6d00355a..6d00355a 100644
--- a/doc/source/command-objects/ip-floating-pool.rst
+++ b/doc/source/cli/command-objects/ip-floating-pool.rst
diff --git a/doc/source/command-objects/ip-floating.rst b/doc/source/cli/command-objects/ip-floating.rst
index 4e5f7b00..4e5f7b00 100644
--- a/doc/source/command-objects/ip-floating.rst
+++ b/doc/source/cli/command-objects/ip-floating.rst
diff --git a/doc/source/command-objects/keypair.rst b/doc/source/cli/command-objects/keypair.rst
index a539f0a2..a539f0a2 100644
--- a/doc/source/command-objects/keypair.rst
+++ b/doc/source/cli/command-objects/keypair.rst
diff --git a/doc/source/command-objects/limits.rst b/doc/source/cli/command-objects/limits.rst
index 92614209..92614209 100644
--- a/doc/source/command-objects/limits.rst
+++ b/doc/source/cli/command-objects/limits.rst
diff --git a/doc/source/command-objects/mapping.rst b/doc/source/cli/command-objects/mapping.rst
index 1f657ed2..1f657ed2 100644
--- a/doc/source/command-objects/mapping.rst
+++ b/doc/source/cli/command-objects/mapping.rst
diff --git a/doc/source/command-objects/module.rst b/doc/source/cli/command-objects/module.rst
index f4b32e75..f4b32e75 100644
--- a/doc/source/command-objects/module.rst
+++ b/doc/source/cli/command-objects/module.rst
diff --git a/doc/source/command-objects/network-agent.rst b/doc/source/cli/command-objects/network-agent.rst
index f69d0ece..f69d0ece 100644
--- a/doc/source/command-objects/network-agent.rst
+++ b/doc/source/cli/command-objects/network-agent.rst
diff --git a/doc/source/command-objects/network-auto-allocated-topology.rst b/doc/source/cli/command-objects/network-auto-allocated-topology.rst
index 4ed68cda..4ed68cda 100644
--- a/doc/source/command-objects/network-auto-allocated-topology.rst
+++ b/doc/source/cli/command-objects/network-auto-allocated-topology.rst
diff --git a/doc/source/command-objects/network-flavor-profile.rst b/doc/source/cli/command-objects/network-flavor-profile.rst
index fdb95059..fdb95059 100644
--- a/doc/source/command-objects/network-flavor-profile.rst
+++ b/doc/source/cli/command-objects/network-flavor-profile.rst
diff --git a/doc/source/command-objects/network-flavor.rst b/doc/source/cli/command-objects/network-flavor.rst
index 2d23bf05..2d23bf05 100644
--- a/doc/source/command-objects/network-flavor.rst
+++ b/doc/source/cli/command-objects/network-flavor.rst
diff --git a/doc/source/command-objects/network-meter-rule.rst b/doc/source/cli/command-objects/network-meter-rule.rst
index 22d50aa9..22d50aa9 100644
--- a/doc/source/command-objects/network-meter-rule.rst
+++ b/doc/source/cli/command-objects/network-meter-rule.rst
diff --git a/doc/source/command-objects/network-meter.rst b/doc/source/cli/command-objects/network-meter.rst
index 6077ce92..6077ce92 100644
--- a/doc/source/command-objects/network-meter.rst
+++ b/doc/source/cli/command-objects/network-meter.rst
diff --git a/doc/source/command-objects/network-qos-policy.rst b/doc/source/cli/command-objects/network-qos-policy.rst
index a75c32fe..a75c32fe 100644
--- a/doc/source/command-objects/network-qos-policy.rst
+++ b/doc/source/cli/command-objects/network-qos-policy.rst
diff --git a/doc/source/command-objects/network-qos-rule-type.rst b/doc/source/cli/command-objects/network-qos-rule-type.rst
index ee53e30b..ee53e30b 100644
--- a/doc/source/command-objects/network-qos-rule-type.rst
+++ b/doc/source/cli/command-objects/network-qos-rule-type.rst
diff --git a/doc/source/command-objects/network-qos-rule.rst b/doc/source/cli/command-objects/network-qos-rule.rst
index 1baf5dbf..1baf5dbf 100644
--- a/doc/source/command-objects/network-qos-rule.rst
+++ b/doc/source/cli/command-objects/network-qos-rule.rst
diff --git a/doc/source/command-objects/network-rbac.rst b/doc/source/cli/command-objects/network-rbac.rst
index c49f29bb..c49f29bb 100644
--- a/doc/source/command-objects/network-rbac.rst
+++ b/doc/source/cli/command-objects/network-rbac.rst
diff --git a/doc/source/command-objects/network-segment.rst b/doc/source/cli/command-objects/network-segment.rst
index d6a66aa0..d6a66aa0 100644
--- a/doc/source/command-objects/network-segment.rst
+++ b/doc/source/cli/command-objects/network-segment.rst
diff --git a/doc/source/command-objects/network-service-provider.rst b/doc/source/cli/command-objects/network-service-provider.rst
index f46073f6..f46073f6 100644
--- a/doc/source/command-objects/network-service-provider.rst
+++ b/doc/source/cli/command-objects/network-service-provider.rst
diff --git a/doc/source/command-objects/network.rst b/doc/source/cli/command-objects/network.rst
index ed9fd13d..ed9fd13d 100644
--- a/doc/source/command-objects/network.rst
+++ b/doc/source/cli/command-objects/network.rst
diff --git a/doc/source/command-objects/object-store-account.rst b/doc/source/cli/command-objects/object-store-account.rst
index e8f09d45..e8f09d45 100644
--- a/doc/source/command-objects/object-store-account.rst
+++ b/doc/source/cli/command-objects/object-store-account.rst
diff --git a/doc/source/command-objects/object.rst b/doc/source/cli/command-objects/object.rst
index 6323c4ed..6323c4ed 100644
--- a/doc/source/command-objects/object.rst
+++ b/doc/source/cli/command-objects/object.rst
diff --git a/doc/source/command-objects/policy.rst b/doc/source/cli/command-objects/policy.rst
index deddf2c4..deddf2c4 100644
--- a/doc/source/command-objects/policy.rst
+++ b/doc/source/cli/command-objects/policy.rst
diff --git a/doc/source/command-objects/port.rst b/doc/source/cli/command-objects/port.rst
index b3f4c7f9..b3f4c7f9 100644
--- a/doc/source/command-objects/port.rst
+++ b/doc/source/cli/command-objects/port.rst
diff --git a/doc/source/command-objects/project-purge.rst b/doc/source/cli/command-objects/project-purge.rst
index 0ad0bbf9..0ad0bbf9 100644
--- a/doc/source/command-objects/project-purge.rst
+++ b/doc/source/cli/command-objects/project-purge.rst
diff --git a/doc/source/command-objects/project.rst b/doc/source/cli/command-objects/project.rst
index cb0941ca..cb0941ca 100644
--- a/doc/source/command-objects/project.rst
+++ b/doc/source/cli/command-objects/project.rst
diff --git a/doc/source/command-objects/quota.rst b/doc/source/cli/command-objects/quota.rst
index f39536af..f39536af 100644
--- a/doc/source/command-objects/quota.rst
+++ b/doc/source/cli/command-objects/quota.rst
diff --git a/doc/source/command-objects/region.rst b/doc/source/cli/command-objects/region.rst
index d2c63c1b..d2c63c1b 100644
--- a/doc/source/command-objects/region.rst
+++ b/doc/source/cli/command-objects/region.rst
diff --git a/doc/source/command-objects/request-token.rst b/doc/source/cli/command-objects/request-token.rst
index 3c80780f..3c80780f 100644
--- a/doc/source/command-objects/request-token.rst
+++ b/doc/source/cli/command-objects/request-token.rst
diff --git a/doc/source/command-objects/role-assignment.rst b/doc/source/cli/command-objects/role-assignment.rst
index b29f32c6..b29f32c6 100644
--- a/doc/source/command-objects/role-assignment.rst
+++ b/doc/source/cli/command-objects/role-assignment.rst
diff --git a/doc/source/command-objects/role.rst b/doc/source/cli/command-objects/role.rst
index fe3126c0..fe3126c0 100644
--- a/doc/source/command-objects/role.rst
+++ b/doc/source/cli/command-objects/role.rst
diff --git a/doc/source/command-objects/router.rst b/doc/source/cli/command-objects/router.rst
index 50e791ea..50e791ea 100644
--- a/doc/source/command-objects/router.rst
+++ b/doc/source/cli/command-objects/router.rst
diff --git a/doc/source/command-objects/security-group-rule.rst b/doc/source/cli/command-objects/security-group-rule.rst
index 1dbf16d2..1dbf16d2 100644
--- a/doc/source/command-objects/security-group-rule.rst
+++ b/doc/source/cli/command-objects/security-group-rule.rst
diff --git a/doc/source/command-objects/security-group.rst b/doc/source/cli/command-objects/security-group.rst
index a95a96f4..a95a96f4 100644
--- a/doc/source/command-objects/security-group.rst
+++ b/doc/source/cli/command-objects/security-group.rst
diff --git a/doc/source/command-objects/server-backup.rst b/doc/source/cli/command-objects/server-backup.rst
index 9ddb2cdf..9ddb2cdf 100644
--- a/doc/source/command-objects/server-backup.rst
+++ b/doc/source/cli/command-objects/server-backup.rst
diff --git a/doc/source/command-objects/server-event.rst b/doc/source/cli/command-objects/server-event.rst
index ef4685f8..ef4685f8 100644
--- a/doc/source/command-objects/server-event.rst
+++ b/doc/source/cli/command-objects/server-event.rst
diff --git a/doc/source/command-objects/server-group.rst b/doc/source/cli/command-objects/server-group.rst
index 97696350..97696350 100644
--- a/doc/source/command-objects/server-group.rst
+++ b/doc/source/cli/command-objects/server-group.rst
diff --git a/doc/source/command-objects/server-image.rst b/doc/source/cli/command-objects/server-image.rst
index 7e625d9e..7e625d9e 100644
--- a/doc/source/command-objects/server-image.rst
+++ b/doc/source/cli/command-objects/server-image.rst
diff --git a/doc/source/command-objects/server.rst b/doc/source/cli/command-objects/server.rst
index cc580603..cc580603 100644
--- a/doc/source/command-objects/server.rst
+++ b/doc/source/cli/command-objects/server.rst
diff --git a/doc/source/command-objects/service-provider.rst b/doc/source/cli/command-objects/service-provider.rst
index 63ef44e1..63ef44e1 100644
--- a/doc/source/command-objects/service-provider.rst
+++ b/doc/source/cli/command-objects/service-provider.rst
diff --git a/doc/source/command-objects/service.rst b/doc/source/cli/command-objects/service.rst
index a69c6950..a69c6950 100644
--- a/doc/source/command-objects/service.rst
+++ b/doc/source/cli/command-objects/service.rst
diff --git a/doc/source/command-objects/snapshot.rst b/doc/source/cli/command-objects/snapshot.rst
index fc516067..fc516067 100644
--- a/doc/source/command-objects/snapshot.rst
+++ b/doc/source/cli/command-objects/snapshot.rst
diff --git a/doc/source/command-objects/subnet-pool.rst b/doc/source/cli/command-objects/subnet-pool.rst
index 3a60974a..3a60974a 100644
--- a/doc/source/command-objects/subnet-pool.rst
+++ b/doc/source/cli/command-objects/subnet-pool.rst
diff --git a/doc/source/command-objects/subnet.rst b/doc/source/cli/command-objects/subnet.rst
index 4e609361..4e609361 100644
--- a/doc/source/command-objects/subnet.rst
+++ b/doc/source/cli/command-objects/subnet.rst
diff --git a/doc/source/command-objects/token.rst b/doc/source/cli/command-objects/token.rst
index b4b14cd9..b4b14cd9 100644
--- a/doc/source/command-objects/token.rst
+++ b/doc/source/cli/command-objects/token.rst
diff --git a/doc/source/command-objects/trust.rst b/doc/source/cli/command-objects/trust.rst
index 28459bca..28459bca 100644
--- a/doc/source/command-objects/trust.rst
+++ b/doc/source/cli/command-objects/trust.rst
diff --git a/doc/source/command-objects/usage.rst b/doc/source/cli/command-objects/usage.rst
index 9cd0f70e..9cd0f70e 100644
--- a/doc/source/command-objects/usage.rst
+++ b/doc/source/cli/command-objects/usage.rst
diff --git a/doc/source/command-objects/user-role.rst b/doc/source/cli/command-objects/user-role.rst
index 4f443f31..4f443f31 100644
--- a/doc/source/command-objects/user-role.rst
+++ b/doc/source/cli/command-objects/user-role.rst
diff --git a/doc/source/command-objects/user.rst b/doc/source/cli/command-objects/user.rst
index 632d0e25..632d0e25 100644
--- a/doc/source/command-objects/user.rst
+++ b/doc/source/cli/command-objects/user.rst
diff --git a/doc/source/command-objects/volume-backup.rst b/doc/source/cli/command-objects/volume-backup.rst
index 585f47d4..585f47d4 100644
--- a/doc/source/command-objects/volume-backup.rst
+++ b/doc/source/cli/command-objects/volume-backup.rst
diff --git a/doc/source/command-objects/volume-host.rst b/doc/source/cli/command-objects/volume-host.rst
index 1e513cb7..1e513cb7 100644
--- a/doc/source/command-objects/volume-host.rst
+++ b/doc/source/cli/command-objects/volume-host.rst
diff --git a/doc/source/command-objects/volume-qos.rst b/doc/source/cli/command-objects/volume-qos.rst
index 8fdbc122..8fdbc122 100644
--- a/doc/source/command-objects/volume-qos.rst
+++ b/doc/source/cli/command-objects/volume-qos.rst
diff --git a/doc/source/command-objects/volume-service.rst b/doc/source/cli/command-objects/volume-service.rst
index 2ad23240..2ad23240 100644
--- a/doc/source/command-objects/volume-service.rst
+++ b/doc/source/cli/command-objects/volume-service.rst
diff --git a/doc/source/command-objects/volume-snapshot.rst b/doc/source/cli/command-objects/volume-snapshot.rst
index 30cc77cc..30cc77cc 100644
--- a/doc/source/command-objects/volume-snapshot.rst
+++ b/doc/source/cli/command-objects/volume-snapshot.rst
diff --git a/doc/source/command-objects/volume-transfer-request.rst b/doc/source/cli/command-objects/volume-transfer-request.rst
index 23cd3d3e..23cd3d3e 100644
--- a/doc/source/command-objects/volume-transfer-request.rst
+++ b/doc/source/cli/command-objects/volume-transfer-request.rst
diff --git a/doc/source/command-objects/volume-type.rst b/doc/source/cli/command-objects/volume-type.rst
index afa293d7..afa293d7 100644
--- a/doc/source/command-objects/volume-type.rst
+++ b/doc/source/cli/command-objects/volume-type.rst
diff --git a/doc/source/command-objects/volume.rst b/doc/source/cli/command-objects/volume.rst
index a06a5d40..a06a5d40 100644
--- a/doc/source/command-objects/volume.rst
+++ b/doc/source/cli/command-objects/volume.rst
diff --git a/doc/source/commands.rst b/doc/source/cli/commands.rst
index cd71bdc8..5c50a1bf 100644
--- a/doc/source/commands.rst
+++ b/doc/source/cli/commands.rst
@@ -1,3 +1,5 @@
+.. _command-structure:
+
 =================
 Command Structure
 =================
@@ -162,9 +164,10 @@ referring to both Compute and Volume quotas.
 Plugin Objects
 --------------
 
-The following are known `Objects` used by OpenStack :doc:`plugins`. These are
-listed here to avoid name conflicts when creating new plugins. For a complete
-list check out :doc:`plugin-commands`.
+The following are known `Objects` used by OpenStack
+:ref:`plugins`. These are listed here to avoid name
+conflicts when creating new plugins. For a complete list check out
+:ref:`plugin-commands`.
 
 * ``action definition``: (**Workflow Engine (Mistral)**)
 * ``action execution``: (**Workflow Engine (Mistral)**)
@@ -281,7 +284,7 @@ Implementation
 
 The command structure is designed to support seamless addition of plugin
 command modules via ``setuptools`` entry points.  The plugin commands must
-be subclasses of Cliff's ``command.Command`` object.  See :doc:`plugins` for
+be subclasses of Cliff's ``command.Command`` object.  See :ref:`plugins` for
 more information.
 
 
diff --git a/doc/source/data/cinder.csv b/doc/source/cli/data/cinder.csv
index 5c89e086..5c89e086 100644
--- a/doc/source/data/cinder.csv
+++ b/doc/source/cli/data/cinder.csv
diff --git a/doc/source/data/glance.csv b/doc/source/cli/data/glance.csv
index 2985e307..2985e307 100644
--- a/doc/source/data/glance.csv
+++ b/doc/source/cli/data/glance.csv
diff --git a/doc/source/data/keystone.csv b/doc/source/cli/data/keystone.csv
index 03c34704..03c34704 100644
--- a/doc/source/data/keystone.csv
+++ b/doc/source/cli/data/keystone.csv
diff --git a/doc/source/data/neutron.csv b/doc/source/cli/data/neutron.csv
index a276cf89..a276cf89 100644
--- a/doc/source/data/neutron.csv
+++ b/doc/source/cli/data/neutron.csv
diff --git a/doc/source/data/nova.csv b/doc/source/cli/data/nova.csv
index 55980391..55980391 100644
--- a/doc/source/data/nova.csv
+++ b/doc/source/cli/data/nova.csv
diff --git a/doc/source/data/swift.csv b/doc/source/cli/data/swift.csv
index 68147412..68147412 100644
--- a/doc/source/data/swift.csv
+++ b/doc/source/cli/data/swift.csv
diff --git a/doc/source/decoder.rst b/doc/source/cli/decoder.rst
index 16810a4c..16810a4c 100644
--- a/doc/source/decoder.rst
+++ b/doc/source/cli/decoder.rst
diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
new file mode 100644
index 00000000..e9aab0af
--- /dev/null
+++ b/doc/source/cli/index.rst
@@ -0,0 +1,15 @@
+====================
+ User Documentation
+====================
+
+.. toctree::
+   :maxdepth: 2
+
+   Manual Page <man/openstack>
+   command-list
+   commands
+   plugin-commands
+   authentication
+   interactive
+   decoder
+   backwards-incompatible
diff --git a/doc/source/interactive.rst b/doc/source/cli/interactive.rst
index 4822d89f..4822d89f 100644
--- a/doc/source/interactive.rst
+++ b/doc/source/cli/interactive.rst
diff --git a/doc/source/man/openstack.rst b/doc/source/cli/man/openstack.rst
index 66a99f32..ab990979 100644
--- a/doc/source/man/openstack.rst
+++ b/doc/source/cli/man/openstack.rst
@@ -1,3 +1,5 @@
+.. _manpage:
+
 ====================
 :program:`openstack`
 ====================
@@ -329,7 +331,7 @@ Logging Settings
 in configuration file. Recording the user operation, it can identify the
 change of the resource and it becomes useful information for troubleshooting.
 
-See :doc:`../configuration` about Logging Settings for more details.
+See :ref:`configuration` about Logging Settings for more details.
 
 
 NOTES
diff --git a/doc/source/plugin-commands.rst b/doc/source/cli/plugin-commands.rst
index ee162f76..55984ffb 100644
--- a/doc/source/plugin-commands.rst
+++ b/doc/source/cli/plugin-commands.rst
@@ -1,3 +1,5 @@
+.. _plugin-commands:
+
 ===============
 Plugin Commands
 ===============
diff --git a/doc/source/configuration.rst b/doc/source/configuration/index.rst
index a49f093a..d2b273d7 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration/index.rst
@@ -1,3 +1,5 @@
+.. _configuration:
+
 =============
 Configuration
 =============
@@ -22,13 +24,13 @@ names by dropping the ``--os-`` prefix if present.
 Global Options
 --------------
 
-The :doc:`openstack manpage <man/openstack>` lists all of the global
+The :ref:`openstack manpage <manpage>` lists all of the global
 options recognized by OpenStackClient and the default authentication plugins.
 
 Environment Variables
 ---------------------
 
-The :doc:`openstack manpage <man/openstack>` also lists all of the
+The :ref:`openstack manpage <manpage>` also lists all of the
 environment variables recognized by OpenStackClient and the default
 authentication plugins.
 
@@ -156,7 +158,7 @@ that appears in :file:`clouds.yaml`
 
 Debugging
 ~~~~~~~~~
-You may find the :doc:`configuration show <command-objects/configuration>`
+You may find the :ref:`configuration show <configuration-show>`
 command helpful to debug configuration issues.  It will display your current
 configuration.
 
diff --git a/doc/source/command-beta.rst b/doc/source/contributor/command-beta.rst
index 669ef201..40ede671 100644
--- a/doc/source/command-beta.rst
+++ b/doc/source/contributor/command-beta.rst
@@ -1,3 +1,5 @@
+.. _command-beta:
+
 ============
 Command Beta
 ============
diff --git a/doc/source/command-errors.rst b/doc/source/contributor/command-errors.rst
index c4adb7d1..c4adb7d1 100644
--- a/doc/source/command-errors.rst
+++ b/doc/source/contributor/command-errors.rst
diff --git a/doc/source/command-logs.rst b/doc/source/contributor/command-logs.rst
index 62126510..62126510 100644
--- a/doc/source/command-logs.rst
+++ b/doc/source/contributor/command-logs.rst
diff --git a/doc/source/command-options.rst b/doc/source/contributor/command-options.rst
index 886c17d2..06623445 100644
--- a/doc/source/command-options.rst
+++ b/doc/source/contributor/command-options.rst
@@ -14,8 +14,8 @@ for defining and using options in all situations.  The alternative of only
 using it when necessary leads to errors when copy-n-paste is used for a
 new command without understanding why or why not that instance is correct.
 
-The :doc:`Human Interface Guide <humaninterfaceguide>`
-describes the guildelines for option names and usage.  In short:
+The :ref:`hig` describes the guildelines for option names and usage.
+In short:
 
 * All option names shall be GNU-style long names (two leading dashes).
 * Some global options may have short names, generally limited to those defined
diff --git a/doc/source/command-wrappers.rst b/doc/source/contributor/command-wrappers.rst
index 2a5d9223..2a5d9223 100644
--- a/doc/source/command-wrappers.rst
+++ b/doc/source/contributor/command-wrappers.rst
diff --git a/doc/source/developing.rst b/doc/source/contributor/developing.rst
index 2981ba4d..2981ba4d 100644
--- a/doc/source/developing.rst
+++ b/doc/source/contributor/developing.rst
diff --git a/doc/source/humaninterfaceguide.rst b/doc/source/contributor/humaninterfaceguide.rst
index b43c71a9..a7db3800 100644
--- a/doc/source/humaninterfaceguide.rst
+++ b/doc/source/contributor/humaninterfaceguide.rst
@@ -1,3 +1,5 @@
+.. _hig:
+
 =====================
 Human Interface Guide
 =====================
@@ -202,7 +204,7 @@ dash ('-') to an underscore ('_'), and converting to upper case.
   ('-') internally between words (:code:`--like-this`).  Underscores ('_') shall not
   be used in option names.
 * Authentication options conform to the common CLI authentication guidelines in
-  :doc:`authentication`.
+  :ref:`authentication`.
 
 For example, :code:`--os-username` can be set from the environment via
 :code:`OS_USERNAME`.
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
new file mode 100644
index 00000000..4438f2ad
--- /dev/null
+++ b/doc/source/contributor/index.rst
@@ -0,0 +1,16 @@
+===========================
+ Contributor Documentation
+===========================
+
+.. toctree::
+   :maxdepth: 1
+
+   developing
+   command-beta
+   command-options
+   command-wrappers
+   command-errors
+   command-logs
+   specs/commands
+   plugins
+   humaninterfaceguide
diff --git a/doc/source/plugins.rst b/doc/source/contributor/plugins.rst
index 058819a6..13f5d495 100644
--- a/doc/source/plugins.rst
+++ b/doc/source/contributor/plugins.rst
@@ -1,3 +1,5 @@
+.. _plugins:
+
 =======
 Plugins
 =======
diff --git a/doc/source/specs/command-objects/example.rst b/doc/source/contributor/specs/command-objects/example.rst
index fa559433..fa559433 100644
--- a/doc/source/specs/command-objects/example.rst
+++ b/doc/source/contributor/specs/command-objects/example.rst
diff --git a/doc/source/specs/commands.rst b/doc/source/contributor/specs/commands.rst
index 5ae0e840..f9d757e7 100644
--- a/doc/source/specs/commands.rst
+++ b/doc/source/contributor/specs/commands.rst
@@ -4,15 +4,15 @@ Command Specs
 
 Specifications for new commands, objects and actions are listed below.
 These specifications have not been implemented. See
-:doc:`Command List <../command-list>` for implemented commands and
-:doc:`Command Structure <../commands>` for implemented objects and actions.
+:ref:`command-list` for implemented commands and
+:ref:`command-structure` for implemented objects and actions.
 
 It is optional to propose a specifications patch for new commands,
 objects and actions here before submitting the implementation. Once your
 specifications patch merges then you may proceed with the implementation.
 Your implementation patches should move applicable portions of the
-specifications patch to the official :doc:`Command List <../command-list>`
-and :doc:`Command Structure <../commands>` documentation.
+specifications patch to the official :ref:`command-list`
+and :ref:`command-structure` documentation.
 
 Objects Specs
 -------------
diff --git a/doc/source/specs/network-topology.rst b/doc/source/contributor/specs/network-topology.rst
index 6789ee97..6789ee97 100755
--- a/doc/source/specs/network-topology.rst
+++ b/doc/source/contributor/specs/network-topology.rst
diff --git a/doc/source/index.rst b/doc/source/index.rst
index ae0ee0ff..be421d20 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -7,32 +7,19 @@ brings the command set for Compute, Identity, Image, Object Storage and
 Block Storage APIs together in a single shell with a uniform command
 structure.
 
-User Documentation
-------------------
-
-.. toctree::
-   :maxdepth: 1
-
-   Manual Page <man/openstack>
-   command-list
-   commands
-   configuration
-   plugins
-   plugin-commands
-   authentication
-   interactive
-   humaninterfaceguide
-   backwards-incompatible
+Using OpenStackClient
+---------------------
 
 .. toctree::
    :maxdepth: 2
 
-   decoder
+   cli/index
+   configuration/index
 
 Getting Started
 ---------------
 
-* Try :doc:`some commands <command-list>`
+* Try :ref:`some commands <command-list>`
 * Read the source `on OpenStack's Git server`_
 * Install OpenStackClient from `PyPi`_ or a `tarball`_
 
@@ -44,19 +31,13 @@ Release Notes
 
    Release Notes <http://docs.openstack.org/releasenotes/python-openstackclient>
 
-Developer Documentation
------------------------
+Contributor Documentation
+-------------------------
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
-   developing
-   command-beta
-   command-options
-   command-wrappers
-   command-errors
-   command-logs
-   specs/commands
+   contributor/index
    api/modules
 
 Project Goals