Merge "Clean up documentation"

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 8bfdcfb..176e0dd 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
@@ -213,7 +213,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
         """
 
@@ -245,7 +245,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