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>

3 files changed, 174 insertions, 0 deletions

diff --git a/doc/source/contributor/specs/command-objects/example.rst b/doc/source/contributor/specs/command-objects/example.rst
new file mode 100644
index 00000000..fa559433
--- /dev/null
+++ b/doc/source/contributor/specs/command-objects/example.rst
@@ -0,0 +1,86 @@
+=======
+example
+=======
+
+This is a specification for the ``example`` command object. It is not intended
+to be a complete template for new commands since other actions, options
+and/or arguments may be used. You can include general specification information
+before the commands below. This information could include links to related material
+or descriptions of similar commands.
+
+[example API name] [example API version]
+
+example create
+--------------
+
+Create new example
+
+.. program:: example create
+.. code:: bash
+
+    openstack example create
+        <name>
+
+.. describe:: <name>
+
+    New example name
+
+example delete
+--------------
+
+Delete example(s)
+
+.. program:: example delete
+.. code:: bash
+
+    openstack example delete
+        <example> [<example> ...]
+
+.. describe:: <example>
+
+    Example(s) to delete (name or ID)
+
+example list
+------------
+
+List examples
+
+.. program:: example list
+.. code:: bash
+
+    openstack example list
+
+example set
+-----------
+
+Set example properties
+
+.. program:: example set
+.. code:: bash
+
+    openstack example set
+        [--name <new-name>]
+        <example>
+
+.. option:: --name <new-name>
+
+    New example name
+
+.. describe:: <example>
+
+    Example to modify (name or ID)
+
+example show
+------------
+
+Display example details
+
+.. program:: example show
+.. code:: bash
+
+    openstack example show
+        <example>
+
+.. describe:: <example>
+
+    Example to display (name or ID)
diff --git a/doc/source/contributor/specs/commands.rst b/doc/source/contributor/specs/commands.rst
new file mode 100644
index 00000000..f9d757e7
--- /dev/null
+++ b/doc/source/contributor/specs/commands.rst
@@ -0,0 +1,44 @@
+=============
+Command Specs
+=============
+
+Specifications for new commands, objects and actions are listed below.
+These specifications have not been implemented. See
+: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 :ref:`command-list`
+and :ref:`command-structure` documentation.
+
+Objects Specs
+-------------
+
+Add specifications for new objects based on the ``example`` object.
+
+Actions Specs
+-------------
+
+Add specifications for new actions based on the ``example`` action.
+
+.. toctree::
+   :maxdepth: 1
+
+   network-topology
+
+Commands Specs
+--------------
+
+Add specifications for new commands based on the commands for the
+``example`` object. The ``example`` commands are not intended to
+be a complete template for new commands since other actions, options
+and/or arguments may be used.
+
+.. toctree::
+   :glob:
+   :maxdepth: 2
+
+   command-objects/*
diff --git a/doc/source/contributor/specs/network-topology.rst b/doc/source/contributor/specs/network-topology.rst
new file mode 100755
index 00000000..6789ee97
--- /dev/null
+++ b/doc/source/contributor/specs/network-topology.rst
@@ -0,0 +1,44 @@
+================
+network topology
+================
+
+A **network topology** shows a topological graph about
+devices which connect to the specific network. Also, it
+will return availability information for each individual
+device within the network as well. One other thing to note
+is that it is the intention for OSC to collect data from
+existing REST APIs
+
+Network v2
+
+network topology list
+---------------------
+
+List network topologies
+
+.. program:: network topology list
+.. code:: bash
+
+    openstack network topology list
+        [--project <project>]
+
+.. option:: --project <project>
+
+    List network topologies for given project
+    (name or ID)
+
+network topology show
+---------------------
+
+Show network topology details
+
+.. program:: network topology show
+.. code:: bash
+
+    openstack network topology show
+        <network>
+
+.. _network_topology_show-network:
+.. describe:: <network>
+
+    Show network topology for a specific network (name or ID)