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

.gitignore

@@ -10,7 +10,6 @@ cover/
 skeleton.egg-info/
 build/
 dist/
-doc/source/api
 AUTHORS
 .update-venv/
 ChangeLog

doc/source/api/api.rst

@@ -0,0 +1,8 @@
+=============
+ oslo.db.api
+=============
+
+.. automodule:: oslo.db.api
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/api/concurrency.rst

@@ -0,0 +1,8 @@
+=====================
+ oslo.db.concurrency
+=====================
+
+.. automodule:: oslo.db.concurrency
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/api/exception.rst

@@ -0,0 +1,8 @@
+===================
+ oslo.db.exception
+===================
+
+.. automodule:: oslo.db.exception
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/api/index.rst

@@ -0,0 +1,12 @@
+=====
+ API
+=====
+
+.. toctree::
+   :maxdepth: 2
+
+   api
+   concurrency
+   exception
+   options
+   sqlalchemy/index

doc/source/api/options.rst

@@ -0,0 +1,8 @@
+=================
+ oslo.db.options
+=================
+
+.. automodule:: oslo.db.options
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/api/sqlalchemy/index.rst

@@ -0,0 +1,9 @@
+====================
+ oslo.db.sqlalchemy
+====================
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *

doc/source/api/sqlalchemy/migration.rst

@@ -0,0 +1,8 @@
+==============================
+ oslo.db.sqlalchemy.migration
+==============================
+
+.. automodule:: oslo.db.sqlalchemy.migration
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/api/sqlalchemy/models.rst

@@ -0,0 +1,8 @@
+===========================
+ oslo.db.sqlalchemy.models
+===========================
+
+.. automodule:: oslo.db.sqlalchemy.models
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/api/sqlalchemy/provision.rst

@@ -0,0 +1,8 @@
+==============================
+ oslo.db.sqlalchemy.provision
+==============================
+
+.. automodule:: oslo.db.sqlalchemy.provision
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/api/sqlalchemy/session.rst

@@ -0,0 +1,8 @@
+============================
+ oslo.db.sqlalchemy.session
+============================
+
+.. automodule:: oslo.db.sqlalchemy.session
+   :members:
+   :undoc-members:
+   :show-inheritance:

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:

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:

doc/source/api/sqlalchemy/utils.rst

@@ -0,0 +1,8 @@
+==========================
+ oslo.db.sqlalchemy.utils
+==========================
+
+.. automodule:: oslo.db.sqlalchemy.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/history.rst

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

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
 ------------------

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.
+be installed system wide.

doc/source/readme.rst

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

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)
-

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

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