Documentation builds failing with Sphinx 1.7.5

Bug #1778603 reported by Lance Bragstad on 2018-06-25
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
OpenStack Identity (keystone)
High
Morgan Fainberg

Bug Description

Sphinx 1.7.5 apparently includes a new warning that is causing our documentation builds to fail.

$ .tox/docs/bin/pip list | grep Sphinx
Sphinx 1.7.5
$ git log -n1
commit 057c59f16fc04e5d4e63f408ac5810ebe6d5ac99
Merge: f5a83da 50fd693
Author: Zuul <email address hidden>
Date: Fri Jun 22 11:48:39 2018 +0000

    Merge "Fix duplicate role names in trusts bug"

The following is the trace when doing `tox -e docs` or `tox -re docs`

reading sources... [ 99%] install/keystone-verify-ubuntu
reading sources... [ 99%] install/shared/note_configuration_vary_by_distribution
reading sources... [ 99%] user/application_credentials
reading sources... [ 99%] user/index
reading sources... [100%] user/json_home

Warning, treated as error:
/home/lbragstad/keystone/keystone/oauth1/validator.py:docstring of keystone.oauth1.validator.OAuthValidator.save_verifier:4:Field list ends without a blank line; unexpected unindent.
ERROR: InvocationError: '/home/lbragstad/keystone/.tox/docs/bin/sphinx-build -W -b html doc/source doc/build/html'

description: updated
Changed in keystone:
status: New → Triaged
importance: Undecided → High
Lance Bragstad (lbragstad) wrote :

I've attempted to remove every comment from the offending file, but the docs tests still fail.

http://paste.openstack.org/show/724267/

Lance Bragstad (lbragstad) wrote :

Note that comment #1 wasn't suggesting that as the fix, simply trying to figure out which comment is causing the failure, since the error from Sphinx isn't very descriptive.

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

Changed in keystone:
assignee: nobody → Lance Bragstad (lbragstad)
status: Triaged → In Progress
Changed in keystone:
assignee: Lance Bragstad (lbragstad) → Morgan Fainberg (mdrnstm)

Change abandoned by Lance Bragstad (<email address hidden>) on branch: master
Review: https://review.openstack.org/577974

Reviewed: https://review.openstack.org/578121
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=589152d094b248da81dc88db2449fb560985ae8b
Submitter: Zuul
Branch: master

commit 589152d094b248da81dc88db2449fb560985ae8b
Author: Lance Bragstad <email address hidden>
Date: Tue Jun 26 14:50:38 2018 +0000

    Override oauthlib docstrings that fail with Sphinx 1.7.5

    Sphinx 1.7.5 has some breaking changes that treat a couple specific
    warnings as errors. Keystone isn't failing on them directly, but we
    do rely on an interface from oauthlib/oauthlib that has compatibility
    issues with that version of Sphinx.

    This commit overrides those comments in keystone's implementation of
    the interface so that we can get our documentation job passing. Once
    the oauthlib docstrings are fixed upstream, we can consume a version
    of oauthlib that addresses those incompatibilities and remove the
    duplication introduced here. This has been reported upstream in the
    following GitHub issue:

      https://github.com/oauthlib/oauthlib/issues/558

    Change-Id: I197bc346ffb2ed75ba68aa2e9c2f82a0cad163e6
    Partial-Bug: 1778603

To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.