doc: Restructure docs for doc-migration

We have three populated sections:

- install
- user
- reference

There are three docs removed, as they served little useful purpose and
were mostly unreferenced.

Sphinx's 'warning-is-error' option is enabled to catch the few issues
that has snuck into the docs.

Change-Id: I04e426faf337f0b03175f439c80b3369d4066733

doc/source/changelog.rst

@@ -1 +0,0 @@
-.. include:: ../../ChangeLog

doc/source/contributing.rst

@@ -1,4 +0,0 @@
-============
-Contributing
-============
-.. include:: ../../CONTRIBUTING.rst

doc/source/index.rst

@@ -1,50 +1,30 @@
-os-brick |release| Documenation
-===============================
+========
+os-brick
+========
 
-Overview
---------
-**os-brick** is a Python package containing classes that help
-with volume discovery and removal from a host.
-
-:doc:`installation`
-  Instructions on how to get the distribution.
-
-:doc:`tutorial`
-  Start here for a quick overview.
-
-:doc:`api/index`
-  The complete API Documenation, organized by module.
-
-
-Changes
--------
-see the :doc:`changelog` for a full list of changes to **os-brick**.
-
-About This Documentation
-------------------------
-This documentation is generated using the `Sphinx
-<http://sphinx.pocoo.org/>`_ documentation generator. The source files
-for the documentation are located in the *doc/* directory of the
-**os-brick** distribution. To generate the docs locally run the
-following command from the root directory of the **os-brick** source.
-
-.. code-block:: bash
-
-   $ python setup.py doc
+`os-brick` is a Python package containing classes that help with volume
+discovery and removal from a host.
 
+Installation Guide
+------------------
 
 .. toctree::
-   :hidden:
+   :maxdepth: 2
 
-   installation
-   tutorial
-   changelog
-   api/index
+   install/index
 
+Usage Guide
+-----------
 
-Indices and tables
-==================
+.. toctree::
+   :maxdepth: 2
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   user/tutorial
+
+Reference
+---------
+
+.. toctree::
+   :maxdepth: 2
+
+   reference/index

doc/source/install/index.rst

@@ -0,0 +1,24 @@
+============
+Installation
+============
+
+At the command line:
+
+.. code-block:: shell
+
+   $ pip install os-brick
+
+Or, if you have virtualenvwrapper installed:
+
+.. code-block:: shell
+
+   $ mkvirtualenv os-brick
+   $ pip install os-brick
+
+Or, from source:
+
+.. code-block:: shell
+
+   $ git clone https://github.com/openstack/os-brick
+   $ cd os-brick
+   $ python setup.py install

doc/source/installation.rst

@@ -1,18 +0,0 @@
-============
-Installation
-============
-
-At the command line::
-
-    $ pip install os-brick
-
-Or, if you have virtualenvwrapper installed::
-
-    $ mkvirtualenv os-brick
-    $ pip install os-brick
-
-Or, from source::
-
-    $ git clone https://github.com/openstack/os-brick
-    $ cd os-brick
-    $ python setup.py install

doc/source/readme.rst

@@ -1 +0,0 @@
-.. include:: ../../README.rst

doc/source/tutorial.rst

@@ -1,36 +0,0 @@
-Tutorial
-========
-
-This tutorial is intended as an introduction to working with
-**os-brick**.
-
-Prerequisites
--------------
-Before we start, make sure that you have the **os-brick** distribution
-:doc:`installed <installation>`. In the Python shell, the following
-should run without raising an exception:
-
-.. code-block:: bash
-
-  >>> import os_brick
-
-Fetch all of the initiator information from the host
-----------------------------------------------------
-An example of how to collect the initiator information that is needed
-to export a volume to this host.
-
-.. code-block:: python
-
- from os_brick.initiator import connector
-
- # what helper do you want to use to get root access?
- root_helper = "sudo"
- # The ip address of the host you are running on
- my_ip = "192.168.1.1"
- # Do you want to support multipath connections?
- multipath = True
- # Do you want to enforce that multipath daemon is running?
- enforce_multipath = False
- initiator = connector.get_connector_properties(root_helper, my_ip,
-                                                multipath,
-                                                enforce_multipath)

doc/source/user/tutorial.rst

@@ -0,0 +1,38 @@
+========
+Tutorial
+========
+
+This tutorial is intended as an introduction to working with **os-brick**.
+
+Prerequisites
+-------------
+
+Before we start, make sure that you have the **os-brick** distribution
+:doc:`installed </install/index>`. In the Python shell, the following should
+run without raising an exception:
+
+.. code-block:: bash
+
+   >>> import os_brick
+
+Fetch all of the initiator information from the host
+----------------------------------------------------
+
+An example of how to collect the initiator information that is needed to export
+a volume to this host.
+
+.. code-block:: python
+
+   from os_brick.initiator import connector
+
+   # what helper do you want to use to get root access?
+   root_helper = "sudo"
+   # The ip address of the host you are running on
+   my_ip = "192.168.1.1"
+   # Do you want to support multipath connections?
+   multipath = True
+   # Do you want to enforce that multipath daemon is running?
+   enforce_multipath = False
+   initiator = connector.get_connector_properties(root_helper, my_ip,
+                                                  multipath,
+                                                  enforce_multipath)

os_brick/initiator/connectors/local.py

@@ -45,10 +45,10 @@ class LocalConnector(base.BaseLinuxConnector):
     def connect_volume(self, connection_properties):
         """Connect to a volume.
 
-        :param connection_properties: The dictionary that describes all
-                                      of the target volume attributes.
-               connection_properties must include:
-               device_path - path to the volume to be connected
+        :param connection_properties: The dictionary that describes all of the
+          target volume attributes. ``connection_properties`` must include:
+
+          - ``device_path`` - path to the volume to be connected
         :type connection_properties: dict
         :returns: dict
         """

setup.cfg

@@ -35,6 +35,7 @@ tag_date = 0
 tag_svn_revision = 0
 
 [build_sphinx]
+warning-is-error = 1
 source-dir = doc/source
 build-dir = doc/build
 all_files = 1