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>
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 was briefly detailed before, but the variant of 'build_sphinx'
provided by 'pbr' does a lot for us that should be documented somewhere.
Change-Id: I0b1877c565d7771e7f0dfdf9198ff41bcd051dec
Include the ChangeLog content in the published documentation to make it
possible to read without downloading the source. Add a link to the new
page to the readme for discoverability.
Change-Id: I3cc06846b6d84f5b175a33a48838c8a6a5e1771d
Closes-Bug: #1681725
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
Avoid cyclic dependencies between pbr and oslosphinx. So if oslosphinx is not
available, continue to be able to generate the documentation.
Change-Id: I4c1f8ea5cded268388dab29931055223f8999c8a
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
Clarify what tools provide what sections in 'setup.cfg', thus explaining
why, for example, I couldn't find any references to '[build_sphinx]' in
either the pbr or setuptools source.
Comments are not a section, so this little bit of info is moved to a
'note'.
Change-Id: Icfb58195c58813e98ab48943119f53c7711331ec
A "testr" entry-point was added to PBR in
I2227adf3643ffe6bcece0c7d2127d23e20d52f7a in Jun 2013. However,
testrepository had already started providing this same
disutils.commands entry-point in Jan 2013 [1].
I am not sure if it is deterministic who wins when two packages
declare the same entry-point, but at least for me, running "python
setup.py testr ..." was not calling into any of the pbr hooks. I
discovered this because I wanted to use the --coverage-package-name
argument provided by the pbr testr wrapper because to s/-/_ in dib.
The original change (I8e4bc9bb78be37b4d13f8d6c2edfe2d67554ad78)
overrides the setuptools provided "test" [2] to call testrepository
when it sees a .testr.conf file (falling back to nose for
compatability). So it seems the intention was not to add a "testr"
command, but that "test" is overridden to run testr automatically when
available.
Therefore I think that testrepository owns the distutils.command
entry-point for "testr". To avoid confusion we should remove the
duplicate entry-point here and just leave the "test" command
overrides.
I've added documentation on the test command. The testr/test split is
quite confusing, being only one letter different, so that is called
out explicitly. Comments in testr_command are updated to reflect
what's happening better. This also converts the calls in tox.ini to
use the PBR wrapper "test".
[1] 2a36806c69 (diff-2eeaed663bd0d25b7e608891384b7298R96)
[2] https://github.com/pypa/setuptools/blob/master/setuptools/command/test.py
Change-Id: I5b68f03e782fef5c45424c04cc851be5988f9019
I noticed the current API documentation is unreadable [1]. Remove the
inbuilt theme and move to oslosphinx for module/api documentation.
[1] http://docs.openstack.org/developer/pbr/api/pbr.version.html
Change-Id: I8d92d849b8a2ab4baca960ae8c271214d3c2b8f4
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>
While there's nothing wrong with a double that, when reading this
section I found that it was a bit distracting and made the section
harder to parse than necessary.
Change-Id: I9ca982a8ad6b3a6fd5c4a8b42b93ad2540b2f1ee
We are silently dropping requirements that do not parse, do not do this
and bubble the error up.
Change-Id: I5bfce7c7d0be2ccd880e78509856074a09c57166
Closes-Bug: 1554331
Tweak wording to slightly clarify how revision tags get turned into
version numbers.
Depends-On: Ie70cb124120d1012d38e5189044c21b83be20819
Change-Id: I29da8e28047015c3c34f04c4443e09d9ade416dc
Fix some inconsistencies in the document like different level indents
and missing italic formatting.
Change-Id: I4913fd00bcd885dec360a5e133cd962caaf8bdc2
Partial-bug: #1509376
The section on 'requirements.txt' files is rather detailed. This
particular section, given its location in the document, should provide
an overview of what pbr does RE: requirements files without going into
implementation specifics. These implementation specifics should instead
be covered in the 'Usage' section.
Rework the existing 'Requirements' sub-section within the 'What It
Does' section such that it only provides a high-level overview. Add the
more detailed explanation of this feature as a new sub-section within
the 'Usage' section.
Change-Id: Id1d6954e647baae93ee0148445946d78d9d36ca5
Partial-bug: #1509376
The usage section isn't very clear: it assumes a lot of setuptools
knowledge on behalf of the user when one of the goals is to abstract
away this knowledge.
Begin reworking it by restructuring the existing content. Move the
'setup.py' sub-section to the top, as it's arguably the most important
file, then slightly rework the 'setup.cfg' sub-section.
Change-Id: I85e136e8817e294ce9b536b4f3ee7f262cc3cd2c
Partial-bug: #1509376
pbr is capable of generating a manifest without the need for an explicit
'MANIFEST.in' file, yet this is not stated anywhere. Correct this
oversight.
Change-Id: If9f8a5de20e78286d47da07adc558ace88e039df
Partial-bug: #1509376
When having a requirement for just a specific python version,
the correct check for i.e. python 2.6 is "python_version=='2.6'"
Change-Id: I65a7481dd0575f105839685ad037d8921d64286a
The docs for environment markers in setup.cfg [extras] had a
couple of issues.
1) There was a space after the package name.
2) python_environment was used where python_version is the marker.
Change-Id: Idbc72c45ae240356ca39eeba6db754f56c6a0f23
After digging in pbr and sphinx source code for a day to figure out
what I was doing wrong, let's update the pbr docs with respect to
building docs using the autodoc features in pbr.
Specifically, document the autodoc_tree_excludes and warnerrors
options and point out that you will probably need to set the
exclude_patterns options in your sphinx config when excluding
modules from the docs build and warnerrors=True. Also provide
some links to the Sphinx docs for more details.
Related-Bug: #1260495
Related-Bug: #1472276
Change-Id: Ib43830d08a156f37a3763ad2807d5c1f4cdbe3fe
Comments are not directly handled by PBR, this documents a reasonable working
set of comments that can be used in setup.cfg.
Comments are parsed out over three locations, configparser, which varies rather
significantly between two and three, pkg_resources, and lastly when pip runs.
Change-Id: Iedebc5baca4e21081708971540d6eab89e043f05
Make it obvious to the reader that data_files installation target
location translates to the actual system-wide root filesystem tree
when installed with sufficient permissions to do so.
Change-Id: I67a4dc61ab89b96b4f5e1f99f0199e5a3247412a
This adds support for reading extras from setup.cfg.
It also adds support for handling environment markers, both in the
extras section and in install_requires and in requirements.txt.
Change-Id: I6fd8276012e65f82934df9c374613b1ce6856b5a
We don't depend on recursive installations via pip - and pip certainly
doesn't support that. We removed part of it recently, finish removing
it all.
Change-Id: I29bc4070b355e52124ceae459ea20403d134b60a
Instead test pip install more thoroughly.
Also document that we don't support setup.py install's easy-install
behaviour.
Change-Id: I87872a69425f9d4f17047e584c12516508d57b16
This reverts commit 8cdb41cf1264e71fd2f479efa7decd38c1f91cfa.
https://www.python.org/dev/peps/pep-0426/#environment-markers is the
right approach for this, and as we haven't released master its safe to
back this out.
Change-Id: Ic7298fcbde54c6beda67c3c897efa75f1b60b78f
The semver doc that Monty wrote was great, but doesn't work in the
real world. Specifically because 1.dev1 < 1.a1, we're unable to
depend on alphas without our testing getting locked down to the alpha
on PyPI rather than the revision we're trying to test.
This update fixes that by allowing 1.a1.dev1, audits for consistency
with PEP-440, fixes up the contact details now that this is team
maintained and notes that its as much Python specific as Linux
specific. We also remove the never-in-a-release
SemanticVersion.to_release method, as YAGNI.
Change-Id: I005a2386842633e9fcda76adfc523196c8c2c95d
Sem-Ver: feature
The doc uses a familliar word of "packager", but the real name
should be "package maintainer". This fixes it.
Change-Id: Ieab50fe7ed0d666c9c6eff4c0b986765765f1ac4
This patch adds support for choosing a requirements file, based on the
current OS, with the format 'requirements-{osname}'. This can be combined
with the current approach of choosing a requirement file based on the
Python version. The motivation for this is to replace conditional
choosing of packages inside setup.py.
Change-Id: I30c56082bb9b9bcd80128eedcef17b6beb793cf8
Move some developer information for running tests out of the README to
the documentation.
Change the home page link to point to the launchpad page.
Add a link to the bug tracker to the README.
Change-Id: I29bdb071eb64bccc561844c130a256b8f998da5f
Closes-Bug: #1318548
