Keystone docs fail to build with SQLAlchemy 0.9

[Brant Knudson]

When using SQLAlchemy 0.9, the docs fail to build. This is preventing Keystone from moving up to SQLAlchemy 0.9.

There's a commit to update keystone's requirements to SQLAlchemy 0.9 which is failing the docs build: https://review.openstack.org/#/c/82231/

The log there only shows the first failure. When I generate docs on my build system I get the following errors:

 sphinx.errors.SphinxWarning:
 /opt/stack/keystone/keystone/common/sql/__init__.py:docstring of
 keystone.common.sql.relationship:53: ERROR: Unknown interpreted text
 role "paramref".

 sphinx.errors.SphinxWarning:
 /opt/stack/keystone/keystone/openstack/common/db/sqlalchemy/utils.py:
 docstring of keystone.openstack.common.db.sqlalchemy.utils.or_:26:
 WARNING: more than one target found for cross-reference u'and_':
 keystone.common.sql.core.and_, keystone.common.sql.and_

 sphinx.errors.SphinxWarning:
 /opt/stack/keystone/keystone/openstack/common/db/sqlalchemy/utils.py:
 docstring of keystone.openstack.common.db.sqlalchemy.utils.select:12:
 WARNING: undefined label: coretutorial_selecting (if the link has no
 caption the label must precede a section header)

[Doug Hellmann (doug-hellmann)]

https://review.openstack.org/#/c/82370/

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/82370
Committed: https://git.openstack.org/cgit/openstack/oslo-incubator/commit/?id=9fed4ed593000224a74516fedb6c258cfd8c0829
Submitter: Jenkins
Branch: master

commit 9fed4ed593000224a74516fedb6c258cfd8c0829
Author: Brant Knudson <email address hidden>
Date: Sun Mar 23 12:04:26 2014 -0500

    Fix Keystone doc build errors with SQLAlchemy 0.9

    The Keystone docs failed to build when using SQLAlchemy 0.9. Among
    the errors that are reported is this one:

     sphinx.errors.SphinxWarning:
     /opt/stack/keystone/keystone/openstack/common/db/sqlalchemy/utils.py:
     docstring of keystone.openstack.common.db.sqlalchemy.utils.select:12:
     WARNING: undefined label: coretutorial_selecting (if the link has no
     caption the label must precede a section header)

    To fix this, the `select` import was removed from
    openstack.common.db.sqlalchemy.utils, and the callers were
    changed to call sqlalchemy.sql.select.

    Change-Id: I4995afc20c014f3a05aeff1d31a65b21fe279265
    Closes-Bug: #1296333

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/82594

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/82594
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=7a9bd0e04f8cbe0c6c1114e4527ab7d608d7d188
Submitter: Jenkins
Branch: master

commit 7a9bd0e04f8cbe0c6c1114e4527ab7d608d7d188
Author: Brant Knudson <email address hidden>
Date: Mon Mar 24 15:17:49 2014 -0500

    Sync oslo-incubator db.sqlalchemy b9e2499

    oslo-incubator db.sqlalchemy has a change that's needed to
    support SQLAlchemy 0.9.x. This syncs the change from
    oslo-incubator and any other changes that have been made
    since the last sync. The oslo-incubator commit hash is
    b9e249962128b72a118252216eb4f0bcafd46da0

    Here's the list of changes:

    9fed4ed Fix Keystone doc build errors with SQLAlchemy 0.9
    5b7e61c Dispose db connections pool on disconnect
    d1988b9 Set sql_mode callback on connect instead of checkout

    Do this to recreate:

     $ python update.py --nodeps --base keystone \
         --dest-dir ../keystone --modules db.sqlalchemy

    Change-Id: I93b310d30fc471f52487087597c4d9974a0d722c
    Partial-Bug: #1296333

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/82367
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=3d2a715025af1ff64cba3691d876bb92b22c0bfa
Submitter: Jenkins
Branch: master

commit 3d2a715025af1ff64cba3691d876bb92b22c0bfa
Author: Brant Knudson <email address hidden>
Date: Sun Mar 23 11:55:59 2014 -0500

    Fix doc build errors with SQLAlchemy 0.9

    The docs failed to build when using SQLAlchemy 0.9. The following
    errors occur:

     sphinx.errors.SphinxWarning:
     /opt/stack/keystone/keystone/common/sql/__init__.py:docstring of
     keystone.common.sql.relationship:53: ERROR: Unknown interpreted text
     role "paramref".

    To fix this, relationship was removed from keystone.common.sql. It
    was a reference to the same in sqlalchemy.orm, so the user was
    changed to use sqlalchemy.orm.relationship.

     sphinx.errors.SphinxWarning:
     /opt/stack/keystone/keystone/openstack/common/db/sqlalchemy/utils.py:
     docstring of keystone.openstack.common.db.sqlalchemy.utils.or_:26:
     WARNING: more than one target found for cross-reference u'and_':
     keystone.common.sql.core.and_, keystone.common.sql.and_

    To fix this, and_ was removed from keystone.common.sql. It was a
    reference to the same in sqlalchemy, so the users were changed to use
    sqlalchemy.and_.

    Closes-Bug: #1296333
    Change-Id: I39a91a5a30d351c4538d437c7584544bdb59c65e