2.1.0: sphinx.errors.SphinxWarning: WARNING: no "man_pages" config value found; no manual pages will be written

Here is a patch to blacklist pbr 2.1.0 from upper-constraints in openstack:

https://review.openstack.org/455865

FWIW, commenting out the man_pages = [] is a workaround

I blame pbr for this but not the part that you'd expect. By default, pbr will build both HTML and man page output [1], but this isn't documented anywhere. This is a nonsensical default, given that the vast majority of projects (_everything_ within the oslo tent, to start) don't need man pages. With the change Matt links to, Sphinx will now correctly fail when attempting to build man pages because there aren't any man pages to build.

I think that feature, more so than anything else, should be changed. This would probably necessitate a major version bump (as a breaking change) and changes in the projects that _do_ want man page output (specifying 'builders' or waiting for Sphinx 1.6 which allows you to specify multiple builders using the stock 'builder' configuration option [2])

[1] https://github.com/openstack-dev/pbr/blob/2.1.0/pbr/builddoc.py#L66
[2] https://github.com/sphinx-doc/sphinx/commit/2afa0b6627f7e5afb188d5a60c8c4767f6250774

The thing is that it's not actually trying to build the man pages, it's just initializing things so we can check if we need to build man pages. Sphinx logs a warning that there are no man pages, which would be fine except that if warning-is-error is set then that becomes fatal. Since the idea of warning-is-error is to catch warnings in the doc build itself, maybe we just catch and ignore the exception around the initialization?

Reviewed: https://review.openstack.org/456156
Committed: https://git.openstack.org/cgit/openstack-dev/pbr/commit/?id=d4e4efd77963ef95906cfbac73468f80cd8e3330
Submitter: Jenkins
Branch: master

commit d4e4efd77963ef95906cfbac73468f80cd8e3330
Author: Stephen Finucane <email address hidden>
Date: Wed Apr 12 10:38:31 2017 +0100

    Stop building man pages by default

    From pretty much the beginning [1], pbr has defaulted to building both
    man page and html output, but has failed to document it anywhere. People
    tend to copy-paste their 'setup.py' and 'conf.py', or rely on the
    'cookiecutter' project, with very little understanding of what's going
    on under the hood (and why would you care - it's docs :)). This means
    that the vast majority of folks using 'pbr' (basically everyone in
    OpenStack) have been unwittingly building "man pages" as part of their
    doc builds for no good reason, which has also led to a lot of confusion
    when this magic behavior is the cause of bugs [2][3].

    There's no good reason that pbr should default to building both man
    pages and html output. For folks that want this functionality, we should
    document it so they can use it. For everyone else though, let's do the
    sane thing and output html like the standard 'build_sphinx' plugin.

    [1] https://github.com/openstack-dev/pbr/commit/5b8b7f1d
    [2] https://bugs.launchpad.net/pbr/+bug/1681983
    [3] https://bugs.launchpad.net/oslotest/+bug/1379998

    Change-Id: I579134a2b7980669180c1666503b848835cc2957
    Closes-Bug: #1681983

This issue was fixed in the openstack-dev/pbr 3.0.0 release.