Many tracebacks building keystone docs

[Clark Boylan]

When building keystone's documentation with tox -e venv -- python setup.py build_sphinx there are many errors/tracebacks. You can see examples at http://logs.openstack.org/86/320586/61/check/gate-keystone-docs/e10418b/console.html#_2016-07-12_18_34_14_520037.

To reproduce run:

  tox -e venv -- python setup.py build_sphinx

[Steve Martinelli (stevemar)]

confirmed it happens, low impacting, but should still be fixed

[Eric Brown (ericwb)]

There are so many exceptions, I think it would be better to split up each

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/372796
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=4d08a1c015713b73f611126e61680ccb25bdbc00
Submitter: Jenkins
Branch: master

commit 4d08a1c015713b73f611126e61680ccb25bdbc00
Author: Eric Brown <email address hidden>
Date: Mon Sep 19 15:30:33 2016 -0700

    Fix for unindent warning in doc build

    Trivial fix for the following:

    /home/ericwb/keystone/doc/source/upgrading.rst:115: WARNING:
    Enumerated list ends without a blank line; unexpected unindent.

    Partial-Bug: #1602422
    Change-Id: Ia1e65267440df6dd43e7b5fe47f86f871a13975d

[OpenStack Infra (hudson-openstack)]

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

commit b9c8963d0ae96ca6eccea4033fb5bbcf2aac4f54
Author: Gage Hugo <email address hidden>
Date: Wed Dec 7 15:31:56 2016 -0600

    Fixed multiple warnings in tox -edocs

    There are multiple tracebacks and warnings being thrown whenever
    the keystone docs are built due to documents being moved/deleted as
    well as formatting issues in a couple places.

    This fixes a few of the warnings due to broken links and fixes a few
    of the method docs.

    Master: http://paste.openstack.org/show/591730/
    This Patch: http://paste.openstack.org/show/591735/

    Change-Id: I11cbbc7a10fa24dcbf67c76e3061a39a58529c06
    Partial-Bug: #1602422

[OpenStack Infra (hudson-openstack)]

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

[OpenStack Infra (hudson-openstack)]

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

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/417508
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=83b2109ae584825a9c9a86891bfd864abd1fce76
Submitter: Jenkins
Branch: master

commit 83b2109ae584825a9c9a86891bfd864abd1fce76
Author: Gage Hugo <email address hidden>
Date: Fri Jan 6 14:56:30 2017 -0600

    Remove stevedore warning when building docs

    When running "tox -edocs", the following warning is raised:

    WARNING stevedore.named [-] Could not load keystone.notifications

    It looks like the removed line "keystone.notifications" is something
    that was left over from another change [1] and never removed from the
    config-generator. This change removes this line and the warning no
    longer appears as a result.

    [1] I1369fd7835b31e57a094d07deb6a1aacc1d314b5

    Change-Id: I08325abadba94efdb5fc405f859bdcb766914782
    Partial-Bug: #1602422

[OpenStack Infra (hudson-openstack)]

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

commit ebbc06ebb9b0b146874c9d95eb7cf16fb7c8590e
Author: Gage Hugo <email address hidden>
Date: Fri Jan 6 14:06:59 2017 -0600

    Fixed not in toctree warnings when building docs

    This change fixes multiple issues of "WARNING: document isn't included
    in any toctree" that were appearing when building "tox -edocs" by adding
    the pages to the toctree in index.rst.

    Change-Id: Iefc19e4aa8a950ffc35256e0fd22bb6bc7b3d2da
    Partial-Bug: #1602422

[OpenStack Infra (hudson-openstack)]

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

[Gage Hugo (gagehugo)]

So the following stacktraces are related to SQLAlchemy's @hybrid_property and I'm not sure how/if these can be fixed:

/home/ghugo/keystone/doc/source/api/keystone.identity.backends.rst:33: WARNING: autodoc: failed to import attribute u'User.password_created_a
t' from module u'keystone.identity.backends.sql_model'; the following exception was raised:
Traceback (most recent call last):
  File "/home/ghugo/keystone/.tox/docs/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 393, in import_object
    obj = self.get_attr(obj, part)
  File "/home/ghugo/keystone/.tox/docs/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 289, in get_attr
    return safe_getattr(obj, name, *defargs)
  File "/home/ghugo/keystone/.tox/docs/local/lib/python2.7/site-packages/sphinx/util/inspect.py", line 115, in safe_getattr
    raise AttributeError(name)
AttributeError: password_created_at
/home/ghugo/keystone/doc/source/api/keystone.identity.backends.rst:33: WARNING: autodoc: failed to import attribute u'User.password_expires_a
t' from module u'keystone.identity.backends.sql_model'; the following exception was raised:
Traceback (most recent call last):
  File "/home/ghugo/keystone/.tox/docs/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 393, in import_object
    obj = self.get_attr(obj, part)
  File "/home/ghugo/keystone/.tox/docs/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 289, in get_attr
    return safe_getattr(obj, name, *defargs)
  File "/home/ghugo/keystone/.tox/docs/local/lib/python2.7/site-packages/sphinx/util/inspect.py", line 115, in safe_getattr
    raise AttributeError(name)
AttributeError: password_expires_at
/home/ghugo/keystone/doc/source/api/keystone.identity.backends.rst:33: WARNING: autodoc: failed to import attribute u'User.password_is_expired' from module u'keystone.identity.backends.sql_model'; the following exception was raised:
Traceback (most recent call last):
  File "/home/ghugo/keystone/.tox/docs/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 393, in import_object
    obj = self.get_attr(obj, part)
  File "/home/ghugo/keystone/.tox/docs/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 289, in get_attr
    return safe_getattr(obj, name, *defargs)
  File "/home/ghugo/keystone/.tox/docs/local/lib/python2.7/site-packages/sphinx/util/inspect.py", line 115, in safe_getattr
    raise AttributeError(name)
AttributeError: password_is_expired
/home/ghugo/keystone/doc/source/api/keystone.identity.backends.rst:33: WARNING: autodoc: failed to import attribute u'User.password_ref' from module u'keystone.identity.backends.sql_model'; the following exception was raised:
Traceback (most recent call last):
  File "/home/ghugo/keystone/.tox/docs/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 393, in import_object
    obj = self.get_attr(obj, part)
  File "/home/ghugo/keystone/.tox/docs/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 289, in get_attr
    return safe_getattr(obj, name, *defargs)
  File "/home/ghugo/keystone/.tox/docs/local/lib/python2.7/site-packages/sphinx/util/inspect.py", line 115, in safe_getattr
    raise AttributeError(...

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/419663
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=9602807d9c0cc30bfdd60fec9d77c0fa7f1c59a8
Submitter: Jenkins
Branch: master

commit 9602807d9c0cc30bfdd60fec9d77c0fa7f1c59a8
Author: Gage Hugo <email address hidden>
Date: Thu Jan 12 15:29:32 2017 -0600

    Changed 'Driver' reference to 'TokenDriverBase'

    When building keystone docs, the following warning was being thrown:

    keystone/doc/source/api/keystone.token.persistence.rst:26: WARNING:
    missing attribute mentioned in :members: or __all__: module
    keystone.token.persistence, attribute Driver

    It appears that the 'Driver' reference was renamed multiple times but
    wasn't updated in the __init__.py. This change updates the 'Driver'
    reference to 'TokenDriverBase' and the warning no longer appears

    Change-Id: I47ff617ee09097e7b0f0d2a2e4495cfc22a41fb9
    Partial-Bug: #1602422

[OpenStack Infra (hudson-openstack)]

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

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/420171
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=0d2f249f590e7a21ebc49349b46bab3ae77630cd
Submitter: Jenkins
Branch: master

commit 0d2f249f590e7a21ebc49349b46bab3ae77630cd
Author: Gage Hugo <email address hidden>
Date: Fri Jan 13 14:26:27 2017 -0600

    Exclude 'keystone_tempest_plugin' in doc build

    When building keystone docs, autodoc goes through all of
    the project in order to auto-generate api docs. When going
    through 'keystone_tempest_plugin', there are currently 6
    warnings that are emitted due to issues with duplicate
    option errors. These errors seem to be related to duplicate
    named options between tempest and oslo.config, rather than
    keystone.

    Due to these warnings, there are already multiple issues with
    the api page [1] not rendering everything.

    This change adds 'keystone_tempest_plugin' to the exclusion list
    for autodoc and as a result, removes the 6 warnings from doc building
    since 'keystone_tempest_plugin' will no longer be auto-generated
    with incomplete info.

    [1] http://docs.openstack.org/developer/keystone/api/keystone_tempest_plugin.html

    Change-Id: Icb5c518b2f1409e2e9580b14ba1ae0e44995a73c
    Co-Authored-By: Tin Lam <email address hidden>
    Partial-Bug: #1602422

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/421468
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=9785f6a006ad0ef9d6a9a6e6436895401b0cbf7f
Submitter: Jenkins
Branch: master

commit 9785f6a006ad0ef9d6a9a6e6436895401b0cbf7f
Author: Steve Martinelli <email address hidden>
Date: Tue Jan 17 14:35:20 2017 -0500

    switch @hybrid_property to @property

    The purpose of hybrid is so that you can use your attribute at the
    class level in a query. At the instance level, it is identical to
    @property

    A hybrid property is only needed when referenced at the class level,
    for instance.

    class Wozzle(...)

      @hybrid_property
      def foo(..)

    If referencing Wozzle.foo, then you need a hybrid property, otherwise
    a regular @property will work just fine.

    Change-Id: Ifd3ff9a888919e09b80e87282af829bc14693369
    Closes-Bug: 1602422

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/keystone 11.0.0.0b3 development milestone.