Sphinx Warning for ironic.drivers.modules.deploy_utils

[Ruby Loo]

When generating our developer docs, sphinx is issuing a warning, and treating it as an error. Which results in gate-ironic-docs-ubuntu-xenial failing :-(

eg: http://logs.openstack.org/84/465484/12/check/gate-ironic-docs-ubuntu-xenial/c64c147/

2017-05-31 10:49:20.991981 | Running Sphinx v1.6.2
2017-05-31 10:49:21.379217 | Initializing sphinxcontrib.pecanwsme.rest
2017-05-31 10:49:21.427799 | loading pickled environment... not yet created
2017-05-31 10:49:21.450817 | Using openstack theme from /home/jenkins/workspace/gate-ironic-docs-ubuntu-xenial/.tox/venv/local/lib/python2.7/site-packages/oslosphinx/theme
...
2017-05-31 10:50:18.081982 | 2017-05-31 10:50:18.081 8408 INFO sphinx.util [-]
2017-05-31 10:50:18.082250 | 2017-05-31 10:49:27.792 8408 WARNING ironic.drivers.modules.deploy_utils [-] The default value of default_boot_option configuration will change eventually from "netboot" to "local". It is recommended to set an explicit value for it during the transition period
2017-05-31 10:50:18.082337 |
2017-05-31 10:50:18.082361 | Warning, treated as error:
2017-05-31 10:50:18.082415 | The default value of default_boot_option configuration will change eventually from "netboot" to "local". It is recommended to set an explicit value for it during the transition period
2017-05-31 10:50:18.269433 | ERROR: InvocationError: '/home/jenkins/workspace/gate-ironic-docs-ubuntu-xenial/.tox/venv/bin/python setup.py build_sphinx'

[Ruby Loo (rloo)]

It isn't clear to me what that warning is about. We've had that code there for quite awhile, no warning is emitted when using sphinx 1.5.5

In March, we added Sphinx's 'warning-is-error' flag [1] and all was fine until yesterday.
If I turn that flag off (in setup.cfg), the warning is not emitted and all is fine.

[1] https://github.com/openstack/ironic/commit/4cff2ab6d56b01431d52a067aa415d3d0f14f404#diff-380c6a8ebbbce17d55d50ef17d3cf906

[Ruby Loo (rloo)]

FWIW, we're currently blocking sphinx 1.6.1, so 1.6.2 may have inherited similar problems. There aren't any details about why we're blocking 1.6.1 [1]. Doug Hellman may recall...

[1] https://review.openstack.org/#/c/465135/

[Michael Turek (mjturek)]

Jobs yesterday were succeeding using sphinx 1.5.6 (Example http://docs-draft.openstack.org/04/465204/5/check/gate-ironic-docs-ubuntu-xenial/90c7643//doc/build/html/ See "Created using" message at bottom of page)

[Ruby Loo (rloo)]

things I tried:
- changing the offending string, but even if i just used 'foobar', Sphinx emitted that warning. If I removed the entire LOG.warning line, it was fine.
- suppressing all known/documented sphinx warnings via 'suppress_warnings' in our conf.py file [1]. Sphinx still emitted the warning.

I don't want to look at the sphinx code, but it seems to me that 1.6.2 is the culprit. mjturek mentioned that yesterday when it was working, we were using sphinx 1.5.6 in gate...

[1] http://www.sphinx-doc.org/en/stable/config.html, see 'suppress_warnings'.

[Doug Hellmann (doug-hellmann)]

Sphinx has been changed so that if during the process of building the docs anything logs a message at warning level, that counts as emitting a warning and so when the flag to treat warnings as errors is set true the log message itself triggers the failure.

My recommendation is to stop having ironic log things when modules are imported (that's not safe anyway, because you have no idea if the logging stuff is even set up at that point) and do it at runtime somewhere in the code path where the option in question is being used.

[OpenStack Infra (hudson-openstack)]

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

[Ruby Loo (rloo)]

We discussed this on irc today, starting around [1].

Although we could fix this by turning off Sphinx's warning-is-error flag (mentioned in comment 1), it means that we wouldn't find out about other more 'real' Sphinx warnings. And if we did this as a temporary, interim solution, it means we'll have to remember to fix it at some point.

So we decided to fix it. We thought about removing the problematic warning since it has been there for awhile, but realized we cannot, since we don't have a CI to test the real fix (see irc discussion at [2].

The proposed patch (comment 6) just changes the code so that the warnings are emitted via the code path, instead of when the module is imported.

[1] http://eavesdrop.openstack.org/irclogs/%23openstack-ironic/%23openstack-ironic.2017-05-31.log.html#t2017-05-31T13:34:30

[2] http://eavesdrop.openstack.org/irclogs/%23openstack-ironic/%23openstack-ironic.2017-05-31.log.html#t2017-05-31T16:04:04

[OpenStack Infra (hudson-openstack)]

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

[OpenStack Infra (hudson-openstack)]

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

[OpenStack Infra (hudson-openstack)]

Change abandoned by Ruby Loo (<email address hidden>) on branch: master
Review: https://review.openstack.org/469560
Reason: Going to use Pavlo's patch instead, because it emits the warnings at conductor startup: https://review.openstack.org/#/c/469768/

[OpenStack Infra (hudson-openstack)]

Change abandoned by Pavlo Shchelokovskyy (<email address hidden>) on branch: master
Review: https://review.openstack.org/469624
Reason: not flipping the default, moved this check to conductor start https://review.openstack.org/#/c/469768/

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/469768
Committed: https://git.openstack.org/cgit/openstack/ironic/commit/?id=892467dc9bc18a7174965484cd94fd7bd38cb5fd
Submitter: Jenkins
Branch: master

commit 892467dc9bc18a7174965484cd94fd7bd38cb5fd
Author: Pavlo Shchelokovskyy <email address hidden>
Date: Thu Jun 1 09:35:28 2017 +0300

    Move deploy_utils warnings to conductor start

    make these checks once during conductor start after config was parsed.
    This will prevent issuing those warnings on module imports.

    Without it sphinx-build is broken when warnings are treated as failures.

    Change-Id: I455bcc45edae82632aaf4eaebdcd597440d33ad3
    Closes-Bug: #1694724

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/ironic 9.0.0 release.