Setuptools and sphinx [0] have removed support for building docs through
setup.py. This has broken imports which break our own local doc builds.
Lets just remove it all (including the tests) so that we are compatible
with modern setuptools and sphinx.
An alternative approach would be to do conditional imports and continue
to support this for old setuptools and sphinx. But that feels like a
dead end that will be difficult to test. Probably better to rip this
bandaid off.
[0] https://www.sphinx-doc.org/en/master/changes.html#id7
Change-Id: I65038caceb192f495288414079ca0f07ce6318bb
We now have a path away from this feature, so let's deprecate it while
we can.
Change-Id: Idfc34b9085c6da9b8cac24986be5f3bad142d927
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
I went to build infra-specs which specifies sphinx==1.5.6 and hit
Traceback (most recent call last):
File "setup.py", line 29, in <module>
pbr=True)
...
File ".../pbr/builddoc.py", line 235, in run
self._sphinx_run()
File ".../pbr/builddoc.py", line 162, in _sphinx_run
freshenv=self.fresh_env, warningiserror=self.warning_is_error)
File ".../sphinx/application.py", line 244, in __init__
self._init_builder(self.buildername)
File "...//sphinx/application.py", line 311, in _init_builder
raise SphinxError('Builder name %s not registered' % buildername)
sphinx.errors.SphinxError: Builder name h not registered
It appears to be a typo introduced with
I18bbf693bca2f6e49d822ae2940d2170a2b90ce9; make sure we're walking the
self.builders list; not the string self.builder.
Change-Id: Ic038029c361b3ede48f2b495c74430d3ad1eab82
We were treating this a single line, comma- or space-delimited option.
This was incorrect and was causing issues for projects like neutron-lib
when Sphinx 1.7, which switches from optparse to the stricter argparse
was used. In addition, this project was including comments in the
multi-line opt. These were being passed through but Sphinx < 1.7 was
simply ignoring them. These are now filtered out.
Change-Id: I177edf0f44714175da220cf3a960b8f23aa4ab09
Closes-Bug: #1753082
Newer versions of Sphinx have moved the apidoc module into sphinx.ext
and the API is slightly different (the function expects sys.argv[1:]
instead of sys.argv[:]. So, figure out where we can import it from and
set a flag so we can invoke it properly. See this change in sphinx for
details:
87630c8ae8
Change-Id: I8235968f8a474c9e6088d935d0868570b2917c07
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
distutils.log has a warn() function but not a warning() function.
Change-Id: Iebfdb9e4d062d188ef9c73b66007a70f9c289ed2
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
We don't want to support older versions of Sphinx forever. While
OpenStack's global requirements have been bumped to Sphinx 1.6, there
are non-OpenStack users in the wild. Give them a chance to upgrade to
the newer version before we completely remove support.
This also gives us a chance to deprecate the '[sphinx_build] builders'
setuptools option, which is no longer necessary with Sphinx 1.6+. Do
this. The documentation is updated to reflect this (and some references
to a "custom" 'source_dir' option removed, as it's not at all specific
to pbr).
Change-Id: I18bbf693bca2f6e49d822ae2940d2170a2b90ce9
Related-Bug: #1702872
In 'c024066', we resolved an issue with pbr and Sphinx 1.6+ and
implicitly started using Sphinx 1.6's support for declaring multiple
builders as part of the setuptools plugin. However, in doing so, we
neglected to provide a migration path for folks who were using the older
option. This meant folks using the '[sphinx_build] builders' option
would see a breaking change in behavior when upgrading to a pbr release
including the above change. Resolve this issue now.
Note that we want to deprecate support for this option in the future,
but doing so is not a backportable change and will be done separately.
Change-Id: Ic2fe67f932ba26b665110ae66431a5359fc50016
Closes-Bug: #1702872
Related-Bug: #1691129
Allow the user to specify 'api_doc_dir' in the build_sphinx section of
their setup.cfg to control where the auto-generated API documentation is
written.
Change-Id: I2bd5652bb59cbd9c939931ba2e7db1b37d2b30bb
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
As noted by stephenfin, Sphinx 1.6 provides its own code to build doc with
multiple builders. The one provided by pbr so far for Sphinx < 1.6 is not even
compatible with 1.6. This patch fixes that by running the native Sphinx code
for Sphinx > 1.6 and falling back to the old code for older Sphinx versions.
Closes-Bug: #1691129
Change-Id: I5224235b1056a248b246c54e2d99eea94d53c4eb
Sphinx 1.6 will support the definition of multiple builders in a
setup.cfg file like so:
[build_sphinx]
builder = html man
Once we support this version of Sphinx, we should stop carrying the
custom versions of this tooling we use.
Upstreaming things FTW.
Change-Id: Ibf2a003229a4585df96b09da7ca547e201c5aef5
codesearch.o.o shows a single, long-dead project using this [1]. Let's
just remove it and push people to set 'builders' instead in they really
want LaTeX.
[1] http://codesearch.openstack.org/?q=build_sphinx_latex
Change-Id: I820d9c540ae81717d7b33bbb4d2a4031b529b52c
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
pbr currently hard-codes the list of warnings that are to be ignored.
Many OpenStack projects use remote images to add project "badges" based
on tags defined in the governance repository. Ignore the warning caused
by using remote images so we can unbreak documentation builds using
those badges.
Change-Id: If47e3ca6519cc9f70d62cd887707321fe9199f81
Addresses-Bug: #1682467
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
Currently sphinx config is initialized using sphinx.config,
however in recent versions of Sphinx, plugin specific parameters
as man_pages for man builder has been moved to the extension
and is not initialized from sphinx.config but using sphinx.application.
This is making man_pages to be empty when using sphinx 1.5 and man
builder is not properly called.
This patch initializes sphinx config using sphinx.application which
works fine with both old and new Sphinx versions.
Closes-Bug: #1674795
Depends-On: I7bde8fc1f2a7db5bd73635aa197377bf5ac614d2
Change-Id: Ib7c1a6fe8fbb5acfcfcfac61d0b53f080ff2b1e4
This legacy option provided the ability to fail on doc warnings.
However, this functionality is broken in recent releases and now exists
in Sphinx itself (since 1.5.0). Rather that fixing it and causing a
whole load of doc build errors introduced in the time since this option
was broken, remove it, preferring the new Sphinx option instead.
This allows us to remove a lot of test code which is essentially testing
Sphinx functionality only now, based on the assumption that Sphinx do
adequate testing themselves.
Change-Id: Ia4b6adefcd437cb1ceb4558b004c17359df2486d
The revert in Ia6cfbfe5b10a5b714fbb9f21ca61380aaf231638 actually
broke Sphinx 1.3.x support again. Try to fix it for real this
time by avoiding an exception on missing man_pages.
NOTE(dmllr): don't change dict while iterating over it, hopefully
this fixes the gating failure with python 3.5.x
Change-Id: I52d45fa0a0d42de690d3a492068f7bb03483a224
Related-Bug: 1379998
Pass the flag to tell Sphinx to treat warnings as errors.
Add compatability note for versions 1.4.0 and suppress
re-register warnings on subsequent runs.
Change-Id: I680b448471e687919d202e8f2abe57f8ba3b22ee
Closes-Bug: #1496882
Co-Authored-By: Doug Hellmann <doug@doughellmann.com>
Although https://review.openstack.org/#/c/171309/
says Sphinx >=1.3, the actual implementation does not
support Sphinx >=1.3b1 and 1.3.1.
I have seen Sphinx release notes and source codes for
those versions, and found that up to 1.2.3 used
init_values(self) and Sphinx from 1.3b1 used
init_values(self, warn).
So to change the code from >=1.3.1 to >1.2.3, it can
more support Sphinx >=1.3b1 and <1.3.1.
Change-Id: Ia73be8111d3af7f72aaf640e4c7c519a5d0b08c5
Partial-Bug: #1379998
Related-Bug: #1496882
Sphinx >= 1.3 changes:
- Prototypes for init_values() requires a handle to warnings.warn
- New warning for setting the html_theme in conf.py to 'default':
sphinx.errors.SphinxWarning: WARNING: 'default' html theme has been
renamed to 'classic'. Please change your html_theme setting either
to the new 'alabaster' default theme, or to 'classic' to keep using
the old default.
This change deals with the above sphinx updates by adding the handle to
init_values() and setting pbr to _not_ fail on warnings when building the
docs.
Change-Id: Iba92628263e20efca84aeada0e19000f4c9b1fac
The function signature for Sphinx's config.init_values() changed since
version 1.3. That leads to:
TypeError: init_values() takes exactly 2 arguments (1 given)
But the function is already correctly called from
application.Sphinx()'s constructor. So use the configuration object
from the application instead of creating an own config object.
Change-Id: I343c26560bfe5116d5348b50b1890b3442ed845a
Closes-Bug: #1379998
The build_sphinx setuptools command supports selection of a builder.
Support the behaviour of being able to explicitely select any builder
available to sphinx via "python setup.py build_sphinx -b linkcheck", not
just one of the builders specified in the configuration file.
Change-Id: I4c7ddcaf413e1bcc72550b3d920f8a777a710c97
Stop including git sha in version strings
We include it in pbr.json now. Including it is contentious in the world
of python, and it's up for debate as to whether or not it provides value.
Write and read more complex git sha info
Instead of encoding the git sha into the version string, add it to
a metadata file. This will allow us to get out of the business of
arguing with pip and setuptools about version info. In order to make
this really nice, provide a command line utility called "pbr" that has
subcommands to print out the metadata that we're now including in the
egg-info dir.
Only import sphinx during hook processing
When pbr is imported to handle writing the egg_info file because of
the entry point, it's causing sphinx to get imported. This has a
cascading effect once docutils is trying to be installed on a system
with pbr installed. If some of the imports fail along the way, allow
pbr to continue usefully but without the Sphinx extensions
available. Eventually, when everything is installed, those
extensions will work again when the commands for build_sphinx, etc.
are run separately.
Also slip in a change to reorder the default list of environments
run by tox so the testr database is created using a dbm format
available to all python versions.
Integration test PBR commits
Make sure that if a PBR commit is being tested then we install and
use that source rather than the latest PBR release.
Change-Id: Ie121e795be2eef30822daaa5fe8ab1c2315577ae
(cherry picked from commit 65f4fafd90)
(cherry picked from commit cd7da23937)
Closes-Bug: #1403510
Co-Authored-By: Clark Boylan <clark.boylan@gmail.com>
Co-Authored-By: Doug Hellmann <doug@doughellmann.com>
Co-Authored-By: Jeremy Stanley <fungi@yuggoth.org>
Clark Boylan