From cae12025a90995d06217385a80c4210614b542f8 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Mon, 1 Sep 2014 16:33:18 -0400 Subject: 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 | 1 - doc/source/api/api.rst | 8 ++++++++ doc/source/api/concurrency.rst | 8 ++++++++ doc/source/api/exception.rst | 8 ++++++++ doc/source/api/index.rst | 12 ++++++++++++ doc/source/api/options.rst | 8 ++++++++ doc/source/api/sqlalchemy/index.rst | 9 +++++++++ doc/source/api/sqlalchemy/migration.rst | 8 ++++++++ doc/source/api/sqlalchemy/models.rst | 8 ++++++++ doc/source/api/sqlalchemy/provision.rst | 8 ++++++++ doc/source/api/sqlalchemy/session.rst | 8 ++++++++ doc/source/api/sqlalchemy/test_base.rst | 8 ++++++++ doc/source/api/sqlalchemy/test_migrations.rst | 8 ++++++++ doc/source/api/sqlalchemy/utils.rst | 8 ++++++++ doc/source/history.rst | 1 + doc/source/index.rst | 12 +++++++----- doc/source/installation.rst | 7 +------ doc/source/readme.rst | 1 - doc/source/usage.rst | 24 +++++++++++++----------- oslo/db/sqlalchemy/test_migrations.py | 26 +++++++++++++------------- setup.cfg | 2 +- 21 files changed, 145 insertions(+), 38 deletions(-) create mode 100644 doc/source/api/api.rst create mode 100644 doc/source/api/concurrency.rst create mode 100644 doc/source/api/exception.rst create mode 100644 doc/source/api/index.rst create mode 100644 doc/source/api/options.rst create mode 100644 doc/source/api/sqlalchemy/index.rst create mode 100644 doc/source/api/sqlalchemy/migration.rst create mode 100644 doc/source/api/sqlalchemy/models.rst create mode 100644 doc/source/api/sqlalchemy/provision.rst create mode 100644 doc/source/api/sqlalchemy/session.rst create mode 100644 doc/source/api/sqlalchemy/test_base.rst create mode 100644 doc/source/api/sqlalchemy/test_migrations.rst create mode 100644 doc/source/api/sqlalchemy/utils.rst create mode 100644 doc/source/history.rst delete mode 100644 doc/source/readme.rst 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_`, @@ -59,16 +58,16 @@ class WalkVersionsMixin(object): `_pre_upgrade_`, `_check_`, `_post_downgrade_` implementation: - * `_pre_upgrade_`: provide a data appropriate to a - next revision. Should be used an id of revision which going to be - applied. + * `_pre_upgrade_`: provide a data appropriate to + a next revision. Should be used an id of revision which + going to be applied. - * `_check_`: Insert, select, delete operations with - newly applied changes. The data provided by - `_pre_upgrade_` will be used. + * `_check_`: Insert, select, delete operations + with newly applied changes. The data provided by + `_pre_upgrade_` will be used. - *`_post_downgrade_`: check for absence (inability to - use) changes provided by reverted revision. + * `_post_downgrade_`: 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 `. :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 `. :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 -- cgit v1.2.1