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 facing errors related to the new pip resolver, this
topic was discussed on the ML and QA team proposed to
to test lower-constraints [1].
I propose to drop this test because the complexity and recurring pain needed
to maintain that now exceeds the benefits provided by this mechanismes.
Replace assertTrue by assertIn to fix with the latest flake8 version.
Add six in the documentation requirements to fix the build.
Fix the conflict status with hacking.
[1] http://lists.openstack.org/pipermail/openstack-discuss/2020-December/019390.html
Change-Id: I580da15fefd6ad352e69749b77cc4664aef84f9c
There's a little bit of duplication going on here. Resolve this by
moving tests that predominantly focus on FILE to tests/test_FILE.
Change-Id: I29355155853e543d017db00c936bcdc88c1c97ad
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>
Upstream Sphinx now has some new expectations that are no longer being
met by some of our tests because we mock the constructor for the
application class. Fix the test to ensure the application instance has
the needed attributes.
Change-Id: Iad009ce74301c9ffd49ff2b2bab4afd9b7dd1388
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
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 change adds new handling when building a Changelog file
for specific characters that cause documentation building
warnings/errors to be emitted when sphinx tries to generate
a Changelog html page. The changes include:
- Escaping any '*' in a commit, which sphinx will interpret as the
start of a new line and throw a warning.
- Escaping any '_' in a commit, which in certain cases, sphinx will
interpret as an invalid link and create an error.
- Escaping any '`' in a commit, which in certain cases will
cause sphinx to interpet as a literal, and throw a warning.
After this change, any entries in the changelog that contain
the above "invalid" syntax no longer generate sphinx
warnings/errors and the offending entries now generate correctly.
Change-Id: I672ef4c56486e59a384849a4b182d11129726ae9
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
Some of tests use different method of assertTrue(isinstance(A, B))
or assertEqual(type(A), B).
The correct way is to use assertIsInstance(A, B) provided by testtools.
Change-Id: I6c7aa04a3a3aaaab7f428cb86549a4d043af802f
Older versions of git produce log output (using --format specifiers)
that doesn't prefix tags with a "tag:" prefix, though they do using
the --decorate log format. This was a bug in git that was fixed, but
the older git is still in the wild. This change combines both the new
--format specifier method with the --decorate method to find tags even
if used with the old, buggy git, while (hopefully) avoiding
identifying non-tags as tags.
This is based on I6b557687f2428a528a8aa7f76e84797162488887 but tries to
use a single format string that works across all versions of git.
Because the format string has changed, some of the test data has had to
change to reflect the new format.
Change-Id: I58a1b12e0f4054fd25bddc77fabb6c89239561ff
Closes-Bug: #1570458
Co-Authored-By: James Polley <jp@jamezpolley.com>
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>
Some odd version strings can cause SemanticVersion.from_pip_string()
to raise IndexError. This change converts IndexError to ValueError.
Change-Id: Ic3046817b6c5808c61c4a3bc3d912501e6a52274
Closes-Bug: #1570145
The logic that splits the git log lines to find tags gets confused by
parentheses in the commit message and truncates the line at the first
one. To mitigate this, have git emit a null character and split on that.
As a consequence of doing and testing this, fix the bug where
non-semantic-version tags in the tag history would show up in the
ChangeLog.
Change-Id: I5e522d6d374534f2921aaded42780df97c3d1987
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>
Some projects need to not generate and publish documentation for some of
their modules. This patch adds an option to list modules that should be
excluded from documentation auto generation.
Change-Id: I944a6ad5faa113ca26eb32b78be1bfc41e1387ef
ordereddict and importlib used to break when attempted to install
on python 2.7 - but this situation seems to have improved in
modern pip/setuptools. Remove the logic and support for this.
Change-Id: I49d9c9ee3108ad7ec9537f3fcec62e84d4de1680
Back in the day, attempting to install argparse on python 2.7 would
result in failure, as the setup.py of argparse failed hard if it was
attempted. That seems to be fixed, and when we do filter it out of
the list now, we cause problems with python 2.6 and wheels (if we make
a wheel on 2.6 and it depends on argparse, the pbr code means that
argparse doesn't get added properly)
Remove the filtering so that our wheels can be universal.
Closes-bug: #1346357
Change-Id: I49d539ac6fb8ee75f8d32fdfbd20129b13d36499
--use-mailmap is a newer git construct that applies mailmaps to
things that are not using the mailmap aware format strings. But
we're using those format strings, and this breaks on precise.
Simplest thing - don't use the arg, since it's pointless and broken
for us.
Change-Id: Ic8ca062a6936a4f112aa52d0eb209211658611c2
This change makes pbr reads a specific requirement file tight to the
major Python version that is used. So you can add a file such as
requirements-py3.txt to have a specific requirement file for Python 3,
or requirements-py2.txt to have a specific requirement file for
Python 2.
Change-Id: I4b548e9830586f11b82539d334dd5cf4b0445a36
It turns out, git log already knows how to process mailmap files.
Just defer to it and stop processing that in python.
Change-Id: Ib3d6f85683fcbe8b5002117d2ee46dc3c008cae7
Just duplicating the git log isn't particularly exciting. Make
the ChangeLog a list of change subjects grouped by tag.
New output can be seen here: http://paste.openstack.org/show/49999
Change-Id: I7bf4d89dcdba135de663d75895b30963f7a44662
Sphinx builders were hard coded to be html and man in LocalBuildDoc
before. This enables users to config a list of builders in setup.cfg
as a comma seperated list, e.g. html,man,doctest
Change-Id: I3528b208c7e719286fe8816acf65f8efdc5844c6
We keep a list of libraries that should only be installed on python 2.6,
but the check to see if a requirement matches that list was only doing
a simple string equality, which would miss attempts to install version
specified instances of one of them.
Instead, use pkg_resources to parse the potential requirements line and
operate on the parsed project name.
Change-Id: If64e4b2ee6696a0531e3ed6099e63372d47bc851
It's an antipattern to have functional code in an __init__.py. Move it
into base.py to be less anti.
Change-Id: Ib4db548b78e4e760d94099596a3c495a839836dc
A previous patch for windows support made the simple case of passing a
string to run_shell_command complicated with quoting. Clean that up by
reverting to list, which avoids the crazy quoting we had to do.
Change-Id: Ia3b8ac6a57e7400d0aab0d5265c851e536fb4e87
Fixes bug: #1210912
Special characters like <, > or ' need to be escaped on Windows when used
with "cmd /C <command>" as implemented in _run_shell_command
In order to avoid escaping issues, shell spawning has been replaced with
direct command execution. As a consequence, grep/egrep command pipes have
been replaced with Python regular expressions where appropriate.
Change-Id: Idd50fd24f300bce655f99d42cb96e37d29d4cb14
Similar to the work in the packages argument, allow the specification
of a directory to recursively include as part of the install.
Change-Id: Ife0414af468e7fcd4fc419eafc3e19e29efcfc7b
Don't fail on inability to write new ChangeLog or AUTHORS files.
Ignore comments in requirements files
Change-Id: I0c017b493ca1ef3f1c770daf25d8778bd98f02ef
Fixes: bug #1192889
When running tests from the released tarballs, the
AUTHORs related checks are failing due to missing .git
directory and the fallout caused by it.
Change-Id: Ic960863621f1b239ced299f892466537431d44d5
Clark Boylan