diff options
author | Doug Hellmann <doug@doughellmann.com> | 2014-09-01 16:33:18 -0400 |
---|---|---|
committer | Doug Hellmann <doug@doughellmann.com> | 2014-09-04 16:27:00 -0400 |
commit | cae12025a90995d06217385a80c4210614b542f8 (patch) | |
tree | 3abac77cedf87077018aad0b13580c9529947ee8 | |
parent | be6f9a0ff7da10bd272c369d97058bf3546fc508 (diff) | |
download | oslo-db-cae12025a90995d06217385a80c4210614b542f8.tar.gz |
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
-rw-r--r-- | .gitignore | 1 | ||||
-rw-r--r-- | doc/source/api/api.rst | 8 | ||||
-rw-r--r-- | doc/source/api/concurrency.rst | 8 | ||||
-rw-r--r-- | doc/source/api/exception.rst | 8 | ||||
-rw-r--r-- | doc/source/api/index.rst | 12 | ||||
-rw-r--r-- | doc/source/api/options.rst | 8 | ||||
-rw-r--r-- | doc/source/api/sqlalchemy/index.rst | 9 | ||||
-rw-r--r-- | doc/source/api/sqlalchemy/migration.rst | 8 | ||||
-rw-r--r-- | doc/source/api/sqlalchemy/models.rst | 8 | ||||
-rw-r--r-- | doc/source/api/sqlalchemy/provision.rst | 8 | ||||
-rw-r--r-- | doc/source/api/sqlalchemy/session.rst | 8 | ||||
-rw-r--r-- | doc/source/api/sqlalchemy/test_base.rst | 8 | ||||
-rw-r--r-- | doc/source/api/sqlalchemy/test_migrations.rst | 8 | ||||
-rw-r--r-- | doc/source/api/sqlalchemy/utils.rst | 8 | ||||
-rw-r--r-- | doc/source/history.rst | 1 | ||||
-rw-r--r-- | doc/source/index.rst | 12 | ||||
-rw-r--r-- | doc/source/installation.rst | 7 | ||||
-rw-r--r-- | doc/source/readme.rst | 1 | ||||
-rw-r--r-- | doc/source/usage.rst | 24 | ||||
-rw-r--r-- | oslo/db/sqlalchemy/test_migrations.py | 26 | ||||
-rw-r--r-- | setup.cfg | 2 |
21 files changed, 145 insertions, 38 deletions
@@ -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 @@ -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 |