Clean up documentation

Switch to manually generated rst files for the API documentation so we
do not expose private parts of the library.

Fix formatting of usage.rst

Convert bullet list to section headers to fix rendering issues and make
the docs more readable.

Fix formatting of docstrings in classes exposed in the docs to eliminate
warnings/errors from Sphinx.

Add history.rst

Change-Id: I6f500775f801558f7c0c29f180b60f83a7150e02

21 files changed, 145 insertions, 38 deletions

diff --git a/.gitignore b/.gitignore
index cbbf8f8..a447b46 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,7 +10,6 @@ cover/
 skeleton.egg-info/
 build/
 dist/
-doc/source/api
 AUTHORS
 .update-venv/
 ChangeLog
diff --git a/doc/source/api/api.rst b/doc/source/api/api.rst
new file mode 100644
index 0000000..1591cc1
--- /dev/null
+++ b/doc/source/api/api.rst
@@ -0,0 +1,8 @@
+=============
+ oslo.db.api
+=============
+
+.. automodule:: oslo.db.api
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/source/api/concurrency.rst b/doc/source/api/concurrency.rst
new file mode 100644
index 0000000..527883a
--- /dev/null
+++ b/doc/source/api/concurrency.rst
@@ -0,0 +1,8 @@
+=====================
+ oslo.db.concurrency
+=====================
+
+.. automodule:: oslo.db.concurrency
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/source/api/exception.rst b/doc/source/api/exception.rst
new file mode 100644
index 0000000..12b0bf0
--- /dev/null
+++ b/doc/source/api/exception.rst
@@ -0,0 +1,8 @@
+===================
+ oslo.db.exception
+===================
+
+.. automodule:: oslo.db.exception
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst
new file mode 100644
index 0000000..124e451
--- /dev/null
+++ b/doc/source/api/index.rst
@@ -0,0 +1,12 @@
+=====
+ API
+=====
+
+.. toctree::
+   :maxdepth: 2
+
+   api
+   concurrency
+   exception
+   options
+   sqlalchemy/index
diff --git a/doc/source/api/options.rst b/doc/source/api/options.rst
new file mode 100644
index 0000000..40d5a83
--- /dev/null
+++ b/doc/source/api/options.rst
@@ -0,0 +1,8 @@
+=================
+ oslo.db.options
+=================
+
+.. automodule:: oslo.db.options
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/source/api/sqlalchemy/index.rst b/doc/source/api/sqlalchemy/index.rst
new file mode 100644
index 0000000..62fc2b2
--- /dev/null
+++ b/doc/source/api/sqlalchemy/index.rst
@@ -0,0 +1,9 @@
+====================
+ oslo.db.sqlalchemy
+====================
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *
diff --git a/doc/source/api/sqlalchemy/migration.rst b/doc/source/api/sqlalchemy/migration.rst
new file mode 100644
index 0000000..2355cbc
--- /dev/null
+++ b/doc/source/api/sqlalchemy/migration.rst
@@ -0,0 +1,8 @@
+==============================
+ oslo.db.sqlalchemy.migration
+==============================
+
+.. automodule:: oslo.db.sqlalchemy.migration
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/source/api/sqlalchemy/models.rst b/doc/source/api/sqlalchemy/models.rst
new file mode 100644
index 0000000..b902320
--- /dev/null
+++ b/doc/source/api/sqlalchemy/models.rst
@@ -0,0 +1,8 @@
+===========================
+ oslo.db.sqlalchemy.models
+===========================
+
+.. automodule:: oslo.db.sqlalchemy.models
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/source/api/sqlalchemy/provision.rst b/doc/source/api/sqlalchemy/provision.rst
new file mode 100644
index 0000000..7d003d7
--- /dev/null
+++ b/doc/source/api/sqlalchemy/provision.rst
@@ -0,0 +1,8 @@
+==============================
+ oslo.db.sqlalchemy.provision
+==============================
+
+.. automodule:: oslo.db.sqlalchemy.provision
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/source/api/sqlalchemy/session.rst b/doc/source/api/sqlalchemy/session.rst
new file mode 100644
index 0000000..14e6f5a
--- /dev/null
+++ b/doc/source/api/sqlalchemy/session.rst
@@ -0,0 +1,8 @@
+============================
+ oslo.db.sqlalchemy.session
+============================
+
+.. automodule:: oslo.db.sqlalchemy.session
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/source/api/sqlalchemy/test_base.rst b/doc/source/api/sqlalchemy/test_base.rst
new file mode 100644
index 0000000..7794170
--- /dev/null
+++ b/doc/source/api/sqlalchemy/test_base.rst
@@ -0,0 +1,8 @@
+==============================
+ oslo.db.sqlalchemy.test_base
+==============================
+
+.. automodule:: oslo.db.sqlalchemy.test_base
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/source/api/sqlalchemy/test_migrations.rst b/doc/source/api/sqlalchemy/test_migrations.rst
new file mode 100644
index 0000000..4b3c81c
--- /dev/null
+++ b/doc/source/api/sqlalchemy/test_migrations.rst
@@ -0,0 +1,8 @@
+====================================
+ oslo.db.sqlalchemy.test_migrations
+====================================
+
+.. automodule:: oslo.db.sqlalchemy.test_migrations
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/source/api/sqlalchemy/utils.rst b/doc/source/api/sqlalchemy/utils.rst
new file mode 100644
index 0000000..cccc93f
--- /dev/null
+++ b/doc/source/api/sqlalchemy/utils.rst
@@ -0,0 +1,8 @@
+==========================
+ oslo.db.sqlalchemy.utils
+==========================
+
+.. automodule:: oslo.db.sqlalchemy.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/source/history.rst b/doc/source/history.rst
new file mode 100644
index 0000000..69ed4fe
--- /dev/null
+++ b/doc/source/history.rst
@@ -0,0 +1 @@
+.. include:: ../../ChangeLog
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 037fe74..5e96766 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,19 +1,21 @@
-Welcome to oslo.db documentation!
-=================================
+=========
+ oslo.db
+=========
 
 The Oslo database handling library. Provides database connectivity
 to the different backends and helper utils.
 
-Contents:
----------
+Contents
+--------
 
 .. toctree::
    :maxdepth: 2
 
-   readme
    installation
    usage
+   api/index
    contributing
+   history
 
 Indices and tables
 ------------------
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index 254bd9b..96e0ec2 100644
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@@ -6,11 +6,6 @@ At the command line::
 
     $ pip install oslo.db
 
-Or, if you have virtualenvwrapper installed::
-
-    $ mkvirtualenv
-    $ pip install oslo.db
-
 You will also need to install at least one SQL backend::
 
     $ pip install MySQL-python
@@ -30,4 +25,4 @@ your distro. On Ubuntu this is done as follows::
 
 The installation of MySQL-python will fail if libmysqlclient-dev is not
 installed first. Note that even in a virtual environment the MySQL package will
-be installed system wide.
\ No newline at end of file
+be installed system wide.
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
deleted file mode 100644
index a6210d3..0000000
--- a/doc/source/readme.rst
+++ /dev/null
@@ -1 +0,0 @@
-.. include:: ../../README.rst
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 0591ebe..f352ee9 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -1,12 +1,13 @@
-========
-Usage
-========
+=======
+ Usage
+=======
 
-To use oslo.db in a project::
+To use oslo.db in a project:
 
-* Session Handling
+Session Handling
+================
 
-  .. code:: python
+.. code:: python
 
     from oslo.config import cfg
     from oslo.db.sqlalchemy import session as db_session
@@ -28,9 +29,10 @@ To use oslo.db in a project::
         return facade.get_session(**kwargs)
 
 
-* Base class for models usage
+Base class for models usage
+===========================
 
-  .. code:: python
+.. code:: python
 
     from oslo.db import models
 
@@ -41,9 +43,10 @@ To use oslo.db in a project::
         ...
 
 
-* DB API backend support
+DB API backend support
+======================
 
-  .. code:: python
+.. code:: python
 
     from oslo.config import cfg
     from oslo.db import api as db_api
@@ -62,4 +65,3 @@ To use oslo.db in a project::
     # DB-API method
     def do_something(somethind_id):
         return IMPL.do_something(somethind_id)
-
diff --git a/oslo/db/sqlalchemy/test_migrations.py b/oslo/db/sqlalchemy/test_migrations.py
index bdd7c6e..6dc193a 100644
--- a/oslo/db/sqlalchemy/test_migrations.py
+++ b/oslo/db/sqlalchemy/test_migrations.py
@@ -45,10 +45,9 @@ class WalkVersionsMixin(object):
     abstract class mixin. `INIT_VERSION`, `REPOSITORY` and `migration_api`
     attributes must be implemented in subclasses.
 
-    .. _auxiliary-dynamic-methods:
+    .. _auxiliary-dynamic-methods: Auxiliary Methods
 
-    Auxiliary methods
-    -----------------
+    Auxiliary Methods:
 
     `_migrate_up` and `_migrate_down` instance methods of the class can be
     used with auxiliary methods named `_pre_upgrade_<revision_id>`,
@@ -59,16 +58,16 @@ class WalkVersionsMixin(object):
     `_pre_upgrade_<revision_id>`, `_check_<revision_id>`,
     `_post_downgrade_<revision_id>` implementation:
 
-        * `_pre_upgrade_<revision_id>`: provide a data appropriate to a
-        next revision. Should be used an id of revision which going to be
-        applied.
+        * `_pre_upgrade_<revision_id>`: provide a data appropriate to
+           a next revision. Should be used an id of revision which
+           going to be applied.
 
-        * `_check_<revision_id>`: Insert, select, delete operations with
-        newly applied changes. The data provided by
-        `_pre_upgrade_<revision_id>` will be used.
+        * `_check_<revision_id>`: Insert, select, delete operations
+           with newly applied changes. The data provided by
+           `_pre_upgrade_<revision_id>` will be used.
 
-        *`_post_downgrade_<revision_id>`: check for absence (inability to
-        use) changes provided by reverted revision.
+        * `_post_downgrade_<revision_id>`: check for absence
+          (inability to use) changes provided by reverted revision.
 
     Execution order of auxiliary methods when revision is upgrading:
 
@@ -79,6 +78,7 @@ class WalkVersionsMixin(object):
         `downgrade` => `_post_downgrade_###`
 
     .. _migrate: https://sqlalchemy-migrate.readthedocs.org/en/latest/
+
     """
 
     @abc.abstractproperty
@@ -189,7 +189,7 @@ class WalkVersionsMixin(object):
         :type version: str
         :keyword with_data: Whether to verify the absence of changes from
             migration(s) being downgraded, see
-            :ref:`auxiliary-dynamic-methods`.
+            :ref:`auxiliary-dynamic-methods <Auxiliary Methods>`.
         :type with_data: Bool
         """
 
@@ -221,7 +221,7 @@ class WalkVersionsMixin(object):
         :param version: id of revision to upgrade.
         :type version: str
         :keyword with_data: Whether to verify the applied changes with data,
-            see :ref:`auxiliary-dynamic-methods`.
+            see :ref:`auxiliary-dynamic-methods <Auxiliary Methods>`.
         :type with_data: Bool
         """
         # NOTE(sdague): try block is here because it's impossible to debug
diff --git a/setup.cfg b/setup.cfg
index 78097e8..119e2a8 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -59,4 +59,4 @@ output_file = oslo.db/locale/oslo.db.pot
 # NOTE(viktors): uncomment ``warnerrors`` line, when setup.cfg we then
 # want to treat sphinx warnings as errors
 # warnerrors = True
-autodoc_index_modules = True
+#autodoc_index_modules = True