rearrange existing documentation using the new standard layout
Change-Id: I885f1adf4fbfc1137c6c48039096bd7bdf89cbd3 Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454 Signed-off-by: Doug Hellmann <doug@doughellmann.com>
This commit is contained in:
parent
86ca01da6c
commit
2fa5003a05
|
@ -28,7 +28,7 @@ develop-eggs
|
|||
cover
|
||||
AUTHORS
|
||||
ChangeLog
|
||||
doc/source/api
|
||||
doc/source/reference/api/
|
||||
|
||||
# Editor files
|
||||
*~
|
||||
|
|
|
@ -1,3 +1,12 @@
|
|||
==============
|
||||
Contributing
|
||||
==============
|
||||
|
||||
Basic Details
|
||||
=============
|
||||
|
||||
.. include:: ../../../CONTRIBUTING.rst
|
||||
|
||||
Running the Tests for pbr
|
||||
=========================
|
||||
|
|
@ -15,9 +15,6 @@ we depend on setup_requires, for any install_requires we recommend that they
|
|||
be installed prior to running `setup.py install` - either by hand, or by using
|
||||
an install tool such as `pip`.
|
||||
|
||||
What It Does
|
||||
============
|
||||
|
||||
PBR can and does do a bunch of things for you:
|
||||
|
||||
* **Version**: Manage version number based on git revisions and tags
|
||||
|
@ -30,515 +27,14 @@ PBR can and does do a bunch of things for you:
|
|||
* **long_description**: Use your README file as a long_description
|
||||
* **Smart find_packages**: Smartly find packages under your root package
|
||||
|
||||
Version
|
||||
-------
|
||||
|
||||
Versions can be managed two ways - postversioning and preversioning.
|
||||
Postversioning is the default, and preversioning is enabled by setting
|
||||
``version`` in the setup.cfg ``metadata`` section. In both cases version
|
||||
strings are inferred from git.
|
||||
|
||||
If the currently checked out revision is tagged, that tag is used as
|
||||
the version.
|
||||
|
||||
If the currently checked out revision is not tagged, then we take the
|
||||
last tagged version number and increment it to get a minimum target
|
||||
version.
|
||||
|
||||
We then walk git history back to the last release. Within each commit we look
|
||||
for a Sem-Ver: pseudo header, and if found parse it looking for keywords.
|
||||
Unknown symbols are not an error (so that folk can't wedge pbr or break their
|
||||
tree), but we will emit an info level warning message. Known symbols:
|
||||
``feature``, ``api-break``, ``deprecation``, ``bugfix``. A missing
|
||||
Sem-Ver line is equivalent to ``Sem-Ver: bugfix``. The ``bugfix`` symbol causes
|
||||
a patch level increment to the version. The ``feature`` and ``deprecation``
|
||||
symbols cause a minor version increment. The ``api-break`` symbol causes a
|
||||
major version increment.
|
||||
|
||||
If postversioning is in use, we use the resulting version number as the target
|
||||
version.
|
||||
|
||||
If preversioning is in use we check that the version set in the metadata
|
||||
section of `setup.cfg` is greater than the version we infer using the above
|
||||
method. If the inferred version is greater than the preversioning value we
|
||||
raise an error, otherwise we use the version from `setup.cfg` as the target.
|
||||
|
||||
We then generate dev version strings based on the commits since the last
|
||||
release and include the current git sha to disambiguate multiple dev versions
|
||||
with the same number of commits since the release.
|
||||
|
||||
.. note::
|
||||
|
||||
`pbr` expects git tags to be signed for use in calculating versions
|
||||
|
||||
The versions are expected to be compliant with :doc:`semver`.
|
||||
|
||||
The ``version.SemanticVersion`` class can be used to query versions of a
|
||||
package and present it in various forms - ``debian_version()``,
|
||||
``release_string()``, ``rpm_string()``, ``version_string()``, or
|
||||
``version_tuple()``.
|
||||
|
||||
AUTHORS and ChangeLog
|
||||
---------------------
|
||||
|
||||
Why keep an `AUTHORS` or a `ChangeLog` file when git already has all of the
|
||||
information you need? `AUTHORS` generation supports filtering/combining based
|
||||
on a standard `.mailmap` file.
|
||||
|
||||
Manifest
|
||||
--------
|
||||
|
||||
Just like `AUTHORS` and `ChangeLog`, why keep a list of files you wish to
|
||||
include when you can find many of these in git. `MANIFEST.in` generation
|
||||
ensures almost all files stored in git, with the exception of `.gitignore`,
|
||||
`.gitreview` and `.pyc` files, are automatically included in your
|
||||
distribution. In addition, the generated `AUTHORS` and `ChangeLog` files are
|
||||
also included. In many cases, this removes the need for an explicit
|
||||
'MANIFEST.in' file
|
||||
|
||||
Sphinx Autodoc
|
||||
--------------
|
||||
|
||||
Sphinx can produce auto documentation indexes based on signatures and
|
||||
docstrings of your project but you have to give it index files to tell it
|
||||
to autodoc each module: that's kind of repetitive and boring. PBR will scan
|
||||
your project, find all of your modules, and generate all of the stub files for
|
||||
you.
|
||||
|
||||
Sphinx documentation setups are altered to generate man pages by default. They
|
||||
also have several pieces of information that are known to setup.py injected
|
||||
into the sphinx config.
|
||||
|
||||
See the pbr_ section for details on configuring your project for autodoc.
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
You may not have noticed, but there are differences in how pip
|
||||
`requirements.txt` files work and how distutils wants to be told about
|
||||
requirements. The pip way is nicer because it sure does make it easier to
|
||||
populate a virtualenv for testing or to just install everything you need.
|
||||
Duplicating the information, though, is super lame. To solve this issue, `pbr`
|
||||
will let you use `requirements.txt`-format files to describe the requirements
|
||||
for your project and will then parse these files, split them up appropriately,
|
||||
and inject them into the `install_requires`, `tests_require` and/or
|
||||
`dependency_links` arguments to `setup`. Voila!
|
||||
|
||||
You can also have a requirement file for each specific major version of Python.
|
||||
If you want to have a different package list for Python 3 then just drop a
|
||||
`requirements-py3.txt` and it will be used instead.
|
||||
|
||||
Finally, it is possible to specify groups of optional dependencies, or
|
||||
`"extra" requirements`_, in your `setup.cfg` rather than `setup.py`.
|
||||
|
||||
long_description
|
||||
----------------
|
||||
|
||||
There is no need to maintain two long descriptions- and your README file is
|
||||
probably a good long_description. So we'll just inject the contents of your
|
||||
README.rst, README.txt or README file into your empty long_description. Yay
|
||||
for you.
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
`pbr` is a setuptools plugin and so to use it you must use setuptools and call
|
||||
``setuptools.setup()``. While the normal setuptools facilities are available,
|
||||
pbr makes it possible to express them through static data files.
|
||||
|
||||
.. _setup_py:
|
||||
|
||||
setup.py
|
||||
--------
|
||||
|
||||
`pbr` only requires a minimal `setup.py` file compared to a standard setuptools
|
||||
project. This is because most configuration is located in static configuration
|
||||
files. This recommended minimal `setup.py` file should look something like this::
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from setuptools import setup
|
||||
|
||||
setup(
|
||||
setup_requires=['pbr'],
|
||||
pbr=True,
|
||||
)
|
||||
|
||||
.. note::
|
||||
|
||||
It is necessary to specify ``pbr=True`` to enabled `pbr` functionality.
|
||||
|
||||
.. note::
|
||||
|
||||
While one can pass any arguments supported by setuptools to `setup()`,
|
||||
any conflicting arguments supplied in `setup.cfg` will take precedence.
|
||||
|
||||
setup.cfg
|
||||
---------
|
||||
|
||||
The `setup.cfg` file is an ini-like file that can mostly replace the `setup.py`
|
||||
file. It is based on the distutils2_ `setup.cfg` file. A simple sample can be
|
||||
found in `pbr`'s own `setup.cfg` (it uses its own machinery to install
|
||||
itself)::
|
||||
|
||||
[metadata]
|
||||
name = pbr
|
||||
author = OpenStack Foundation
|
||||
author-email = openstack-dev@lists.openstack.org
|
||||
summary = OpenStack's setup automation in a reusable form
|
||||
description-file = README
|
||||
home-page = https://launchpad.net/pbr
|
||||
license = Apache-2
|
||||
classifier =
|
||||
Development Status :: 4 - Beta
|
||||
Environment :: Console
|
||||
Environment :: OpenStack
|
||||
Intended Audience :: Developers
|
||||
Intended Audience :: Information Technology
|
||||
License :: OSI Approved :: Apache Software License
|
||||
Operating System :: OS Independent
|
||||
Programming Language :: Python
|
||||
keywords =
|
||||
setup
|
||||
distutils
|
||||
|
||||
[files]
|
||||
packages =
|
||||
pbr
|
||||
data_files =
|
||||
etc/pbr = etc/*
|
||||
etc/init =
|
||||
pbr.packaging.conf
|
||||
pbr.version.conf
|
||||
|
||||
[entry_points]
|
||||
console_scripts =
|
||||
pbr = pbr.cmd:main
|
||||
pbr.config.drivers =
|
||||
plain = pbr.cfg.driver:Plain
|
||||
|
||||
`pbr` provides its own section in these documents, ostensibly called ``pbr``,
|
||||
and provides a custom version of Sphinx's ``build_sphinx`` section. Most other
|
||||
sections are provided by setuptools and may influence either the build itself
|
||||
or the output of various `setuptools commands`__. The remaining sections are
|
||||
provided by libraries that provide setuptools extensions, such as
|
||||
``extract_mesages`` (provided by `Babel`__). Some of these are described below.
|
||||
|
||||
__ https://setuptools.readthedocs.io/en/latest/setuptools.html#command-reference
|
||||
__ http://babel.pocoo.org/en/latest/setup.html
|
||||
__ http://www.sphinx-doc.org/en/stable/setuptools.html
|
||||
|
||||
.. note::
|
||||
|
||||
Comments may be used in `setup.cfg`, however all comments should start with
|
||||
a `#` and may be on a single line, or in line, with at least one white space
|
||||
character immediately preceding the `#`. Semicolons are not a supported
|
||||
comment delimiter. For instance::
|
||||
|
||||
[section]
|
||||
# A comment at the start of a dedicated line
|
||||
key =
|
||||
value1 # An in line comment
|
||||
value2
|
||||
# A comment on a dedicated line
|
||||
value3
|
||||
|
||||
files
|
||||
~~~~~
|
||||
|
||||
The ``files`` section defines the install location of files in the package
|
||||
using three fundamental keys: ``packages``, ``namespace_packages``, and
|
||||
``data_files``.
|
||||
|
||||
``packages``
|
||||
|
||||
A list of top-level packages that should be installed. The behavior of
|
||||
packages is similar to ``setuptools.find_packages`` in that it recurses the
|
||||
python package hierarchy below the given top level and installs all of it. If
|
||||
``packages`` is not specified, it defaults to the value of the ``name`` field
|
||||
given in the ``[metadata]`` section.
|
||||
|
||||
``namespace_packages``
|
||||
|
||||
Similar to ``packages``, but is a list of packages that provide namespace
|
||||
packages.
|
||||
|
||||
``data_files``
|
||||
|
||||
A list of files to be installed. The format is an indented block that
|
||||
contains key value pairs which specify target directory and source file to
|
||||
install there. More than one source file for a directory may be indicated
|
||||
with a further indented list. Source files are stripped of leading
|
||||
directories. Additionally, `pbr` supports a simple file globbing syntax for
|
||||
installing entire directory structures, thus::
|
||||
|
||||
[files]
|
||||
data_files =
|
||||
etc/pbr = etc/pbr/*
|
||||
etc/neutron =
|
||||
etc/api-paste.ini
|
||||
etc/dhcp-agent.ini
|
||||
etc/init.d = neutron.init
|
||||
|
||||
will result in `/etc/neutron` containing `api-paste.ini` and `dhcp-agent.ini`,
|
||||
both of which pbr will expect to find in the `etc` directory in the root of
|
||||
the source tree. Additionally, `neutron.init` from that dir will be installed
|
||||
in `/etc/init.d`. All of the files and directories located under `etc/pbr` in
|
||||
the source tree will be installed into `/etc/pbr`.
|
||||
|
||||
Note that this behavior is relative to the effective root of the environment
|
||||
into which the packages are installed, so depending on available permissions
|
||||
this could be the actual system-wide `/etc` directory or just a top-level
|
||||
`etc` subdirectory of a virtualenv.
|
||||
|
||||
pbr
|
||||
~~~
|
||||
|
||||
The ``pbr`` section controls `pbr` specific options and behaviours.
|
||||
|
||||
``autodoc_tree_index_modules``
|
||||
|
||||
A boolean option controlling whether `pbr` should generate an index of
|
||||
modules using `sphinx-apidoc`. By default, all files except `setup.py` are
|
||||
included, but this can be overridden using the ``autodoc_tree_excludes``
|
||||
option.
|
||||
|
||||
``autodoc_tree_excludes``
|
||||
|
||||
A list of modules to exclude when building documentation using
|
||||
`sphinx-apidoc`. Defaults to ``[setup.py]``. Refer to the `sphinx-apidoc man
|
||||
page`_ for more information.
|
||||
|
||||
``autodoc_index_modules``
|
||||
|
||||
A boolean option controlling whether `pbr` should itself generates
|
||||
documentation for Python modules of the project. By default, all found Python
|
||||
modules are included; some of them can be excluded by listing them in
|
||||
``autodoc_exclude_modules``.
|
||||
|
||||
``autodoc_exclude_modules``
|
||||
|
||||
A list of modules to exclude when building module documentation using `pbr`.
|
||||
`fnmatch` style pattern (e.g. `myapp.tests.*`) can be used.
|
||||
|
||||
``api_doc_dir``
|
||||
|
||||
A subdirectory inside the ``build_sphinx.source_dir`` where
|
||||
auto-generated API documentation should be written, if
|
||||
``autodoc_index_modules`` is set to True. Defaults to ``"api"``.
|
||||
|
||||
.. note::
|
||||
|
||||
When using ``autodoc_tree_excludes`` or ``autodoc_index_modules`` you may
|
||||
also need to set ``exclude_patterns`` in your Sphinx configuration file
|
||||
(generally found at `doc/source/conf.py` in most OpenStack projects)
|
||||
otherwise Sphinx may complain about documents that are not in a toctree.
|
||||
This is especially true if the ``[sphinx_build] warning-is-error`` option is
|
||||
set. See the `Sphinx build configuration file`_ documentation for more
|
||||
information on configuring Sphinx.
|
||||
|
||||
.. versionchanged:: 2.0
|
||||
|
||||
The ``pbr`` section used to take a ``warnerrors`` option that would enable
|
||||
the ``-W`` (Turn warnings into errors.) option when building Sphinx. This
|
||||
feature was broken in 1.10 and was removed in pbr 2.0 in favour of the
|
||||
``[build_sphinx] warning-is-error`` provided in Sphinx 1.5+.
|
||||
|
||||
build_sphinx
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The ``build_sphinx`` section is a version of the ``build_sphinx`` setuptools
|
||||
plugin provided with Sphinx. This plugin extends the original plugin to add the
|
||||
following:
|
||||
|
||||
- Automatic generation of module documentation using the apidoc__ tool
|
||||
|
||||
- Automatic configuration of the `project`, `version` and `release` settings
|
||||
using information from `pbr` itself
|
||||
|
||||
- Support for multiple builders using the ``builders`` configuration option
|
||||
|
||||
.. note::
|
||||
|
||||
Sphinx 1.6 adds support for multiple builders using the default `builder`
|
||||
option. You should refer to this file for more information.
|
||||
|
||||
The version of ``build_sphinx`` provided by `pbr` provides a single additional
|
||||
option.
|
||||
|
||||
``builders``
|
||||
|
||||
A space or comma separated list of builders to run. For example, to build
|
||||
both HTML and man page documentation, you would define the following in your
|
||||
`setup.cfg`:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[build_sphinx]
|
||||
builders = html,man
|
||||
source-dir = doc/source
|
||||
build-dir = doc/build
|
||||
all-files = 1
|
||||
|
||||
``source_dir``
|
||||
|
||||
The path to the source directory where the Sphinx documentation tree
|
||||
is.
|
||||
|
||||
For information on the remaining options, refer to the `Sphinx
|
||||
documentation`__. In addition, the ``autodoc_index_modules``,
|
||||
``autodoc_tree_index_modules``, ``autodoc_exclude_modules`` and
|
||||
``autodoc_tree_excludes`` options in the ``pbr`` section will affect the output
|
||||
of the automatic module documentation generation.
|
||||
|
||||
.. versionchanged:: 3.0
|
||||
|
||||
The ``build_sphinx`` plugin used to default to building both HTML and man
|
||||
page output. This is no longer the case, and you should explicitly set
|
||||
``builders`` to ``html man`` if you wish to retain this behavior.
|
||||
|
||||
__ http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html
|
||||
__ http://www.sphinx-doc.org/en/stable/setuptools.html
|
||||
|
||||
entry_points
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The ``entry_points`` section defines entry points for generated console scripts
|
||||
and python libraries. This is actually provided by `setuptools`__ but is
|
||||
documented here owing to its importance.
|
||||
|
||||
The general syntax of specifying entry points is a top level name indicating
|
||||
the entry point group name, followed by one or more key value pairs naming
|
||||
the entry point to be installed. For instance::
|
||||
|
||||
[entry_points]
|
||||
console_scripts =
|
||||
pbr = pbr.cmd:main
|
||||
pbr.config.drivers =
|
||||
plain = pbr.cfg.driver:Plain
|
||||
fancy = pbr.cfg.driver:Fancy
|
||||
|
||||
Will cause a console script called `pbr` to be installed that executes the
|
||||
`main` function found in `pbr.cmd`. Additionally, two entry points will be
|
||||
installed for `pbr.config.drivers`, one called `plain` which maps to the
|
||||
`Plain` class in `pbr.cfg.driver` and one called `fancy` which maps to the
|
||||
`Fancy` class in `pbr.cfg.driver`.
|
||||
|
||||
__ https://setuptools.readthedocs.io/en/latest/setuptools.html#options
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
Requirement files should be given one of the below names. This order is also
|
||||
the order that the requirements are tried in (where `N` is the Python major
|
||||
version number used to install the package):
|
||||
|
||||
* requirements-pyN.txt
|
||||
* tools/pip-requires-py3
|
||||
* requirements.txt
|
||||
* tools/pip-requires
|
||||
|
||||
Only the first file found is used to install the list of packages it contains.
|
||||
|
||||
.. note::
|
||||
|
||||
The 'requirements-pyN.txt' file is deprecated - 'requirements.txt' should
|
||||
be universal. You can use `Environment markers`_ for this purpose.
|
||||
|
||||
Extra requirements
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Groups of optional dependencies, or `"extra" requirements`_, can be described
|
||||
in your `setup.cfg`, rather than needing to be added to `setup.py`. An example
|
||||
(which also demonstrates the use of environment markers) is shown below.
|
||||
|
||||
Environment markers
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Environment markers are `conditional dependencies`_ which can be added to the
|
||||
requirements (or to a group of extra requirements) automatically, depending
|
||||
on the environment the installer is running in. They can be added to
|
||||
requirements in the requirements file, or to extras defined in `setup.cfg`,
|
||||
but the format is slightly different for each.
|
||||
|
||||
For ``requirements.txt``::
|
||||
|
||||
argparse; python_version=='2.6'
|
||||
|
||||
This will result in the package depending on ``argparse`` only if it's being
|
||||
installed into Python 2.6
|
||||
|
||||
For extras specified in `setup.cfg`, add an ``extras`` section. For instance,
|
||||
to create two groups of extra requirements with additional constraints on the
|
||||
environment, you can use::
|
||||
|
||||
[extras]
|
||||
security =
|
||||
aleph
|
||||
bet:python_version=='3.2'
|
||||
gimel:python_version=='2.7'
|
||||
testing =
|
||||
quux:python_version=='2.7'
|
||||
|
||||
|
||||
Testing
|
||||
-------
|
||||
|
||||
`pbr` overrides the ``setuptools`` hook ``test`` (i.e. ``setup.py test``). The
|
||||
following sequence is followed:
|
||||
|
||||
#. If a ``.testr.conf`` file exists and `testrepository
|
||||
<https://pypi.python.org/pypi/testrepository>`__ is installed, `pbr`
|
||||
will use it as the test runner. See the ``testr`` documentation
|
||||
for more details.
|
||||
|
||||
.. note::
|
||||
|
||||
This is separate to ``setup.py testr`` (note the extra ``r``) which
|
||||
is provided directly by the ``testrepository`` package. Be careful
|
||||
as there is some overlap of command arguments.
|
||||
|
||||
#. Although deprecated, if ``[nosetests]`` is defined in ``setup.cfg``
|
||||
and `nose <http://nose.readthedocs.io/en/latest/>`__ is installed,
|
||||
the ``nose`` runner will be used.
|
||||
|
||||
#. In other cases no override will be installed and the ``test``
|
||||
command will revert to `setuptools
|
||||
<http://setuptools.readthedocs.io/en/latest/setuptools.html#test-build-package-and-run-a-unittest-suite>`__.
|
||||
|
||||
A typical usage would be in ``tox.ini`` such as::
|
||||
|
||||
[tox]
|
||||
minversion = 2.0
|
||||
skipsdist = True
|
||||
envlist = py33,py34,py35,py26,py27,pypy,pep8,docs
|
||||
|
||||
[testenv]
|
||||
usedevelop = True
|
||||
setenv =
|
||||
VIRTUAL_ENV={envdir}
|
||||
CLIENT_NAME=pbr
|
||||
deps = .
|
||||
-r{toxinidir}/test-requirements.txt
|
||||
commands =
|
||||
python setup.py test --testr-args='{posargs}'
|
||||
|
||||
The argument ``--coverage`` will set ``PYTHON`` to ``coverage run`` to
|
||||
produce a coverage report. ``--coverage-package-name`` can be used to
|
||||
modify or narrow the packages traced.
|
||||
|
||||
Additional Docs
|
||||
===============
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:maxdepth: 2
|
||||
|
||||
packagers
|
||||
semver
|
||||
testing
|
||||
compatibility
|
||||
api/modules
|
||||
history
|
||||
user/index
|
||||
reference/index
|
||||
contributor/index
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
|
|
@ -0,0 +1,8 @@
|
|||
===================
|
||||
pbr API Reference
|
||||
===================
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
|
||||
api/*
|
|
@ -0,0 +1,112 @@
|
|||
==========
|
||||
Features
|
||||
==========
|
||||
|
||||
Version
|
||||
-------
|
||||
|
||||
Versions can be managed two ways - postversioning and preversioning.
|
||||
Postversioning is the default, and preversioning is enabled by setting
|
||||
``version`` in the setup.cfg ``metadata`` section. In both cases version
|
||||
strings are inferred from git.
|
||||
|
||||
If the currently checked out revision is tagged, that tag is used as
|
||||
the version.
|
||||
|
||||
If the currently checked out revision is not tagged, then we take the
|
||||
last tagged version number and increment it to get a minimum target
|
||||
version.
|
||||
|
||||
We then walk git history back to the last release. Within each commit we look
|
||||
for a Sem-Ver: pseudo header, and if found parse it looking for keywords.
|
||||
Unknown symbols are not an error (so that folk can't wedge pbr or break their
|
||||
tree), but we will emit an info level warning message. Known symbols:
|
||||
``feature``, ``api-break``, ``deprecation``, ``bugfix``. A missing
|
||||
Sem-Ver line is equivalent to ``Sem-Ver: bugfix``. The ``bugfix`` symbol causes
|
||||
a patch level increment to the version. The ``feature`` and ``deprecation``
|
||||
symbols cause a minor version increment. The ``api-break`` symbol causes a
|
||||
major version increment.
|
||||
|
||||
If postversioning is in use, we use the resulting version number as the target
|
||||
version.
|
||||
|
||||
If preversioning is in use we check that the version set in the metadata
|
||||
section of `setup.cfg` is greater than the version we infer using the above
|
||||
method. If the inferred version is greater than the preversioning value we
|
||||
raise an error, otherwise we use the version from `setup.cfg` as the target.
|
||||
|
||||
We then generate dev version strings based on the commits since the last
|
||||
release and include the current git sha to disambiguate multiple dev versions
|
||||
with the same number of commits since the release.
|
||||
|
||||
.. note::
|
||||
|
||||
`pbr` expects git tags to be signed for use in calculating versions
|
||||
|
||||
The versions are expected to be compliant with :doc:`semver`.
|
||||
|
||||
The ``version.SemanticVersion`` class can be used to query versions of a
|
||||
package and present it in various forms - ``debian_version()``,
|
||||
``release_string()``, ``rpm_string()``, ``version_string()``, or
|
||||
``version_tuple()``.
|
||||
|
||||
AUTHORS and ChangeLog
|
||||
---------------------
|
||||
|
||||
Why keep an `AUTHORS` or a `ChangeLog` file when git already has all of the
|
||||
information you need? `AUTHORS` generation supports filtering/combining based
|
||||
on a standard `.mailmap` file.
|
||||
|
||||
Manifest
|
||||
--------
|
||||
|
||||
Just like `AUTHORS` and `ChangeLog`, why keep a list of files you wish to
|
||||
include when you can find many of these in git. `MANIFEST.in` generation
|
||||
ensures almost all files stored in git, with the exception of `.gitignore`,
|
||||
`.gitreview` and `.pyc` files, are automatically included in your
|
||||
distribution. In addition, the generated `AUTHORS` and `ChangeLog` files are
|
||||
also included. In many cases, this removes the need for an explicit
|
||||
'MANIFEST.in' file
|
||||
|
||||
Sphinx Autodoc
|
||||
--------------
|
||||
|
||||
Sphinx can produce auto documentation indexes based on signatures and
|
||||
docstrings of your project but you have to give it index files to tell it
|
||||
to autodoc each module: that's kind of repetitive and boring. PBR will scan
|
||||
your project, find all of your modules, and generate all of the stub files for
|
||||
you.
|
||||
|
||||
Sphinx documentation setups are altered to generate man pages by default. They
|
||||
also have several pieces of information that are known to setup.py injected
|
||||
into the sphinx config.
|
||||
|
||||
See the pbr_ section for details on configuring your project for autodoc.
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
You may not have noticed, but there are differences in how pip
|
||||
`requirements.txt` files work and how distutils wants to be told about
|
||||
requirements. The pip way is nicer because it sure does make it easier to
|
||||
populate a virtualenv for testing or to just install everything you need.
|
||||
Duplicating the information, though, is super lame. To solve this issue, `pbr`
|
||||
will let you use `requirements.txt`-format files to describe the requirements
|
||||
for your project and will then parse these files, split them up appropriately,
|
||||
and inject them into the `install_requires`, `tests_require` and/or
|
||||
`dependency_links` arguments to `setup`. Voila!
|
||||
|
||||
You can also have a requirement file for each specific major version of Python.
|
||||
If you want to have a different package list for Python 3 then just drop a
|
||||
`requirements-py3.txt` and it will be used instead.
|
||||
|
||||
Finally, it is possible to specify groups of optional dependencies, or
|
||||
`"extra" requirements`_, in your `setup.cfg` rather than `setup.py`.
|
||||
|
||||
long_description
|
||||
----------------
|
||||
|
||||
There is no need to maintain two long descriptions- and your README file is
|
||||
probably a good long_description. So we'll just inject the contents of your
|
||||
README.rst, README.txt or README file into your empty long_description. Yay
|
||||
for you.
|
|
@ -2,4 +2,4 @@
|
|||
Release History
|
||||
=================
|
||||
|
||||
.. include:: ../../ChangeLog
|
||||
.. include:: ../../../ChangeLog
|
|
@ -0,0 +1,13 @@
|
|||
===========
|
||||
Using pbr
|
||||
===========
|
||||
|
||||
.. toctree::
|
||||
|
||||
features
|
||||
using
|
||||
packagers
|
||||
semver
|
||||
compatibility
|
||||
history
|
||||
|
|
@ -0,0 +1,393 @@
|
|||
=======
|
||||
Usage
|
||||
=======
|
||||
|
||||
`pbr` is a setuptools plugin and so to use it you must use setuptools and call
|
||||
``setuptools.setup()``. While the normal setuptools facilities are available,
|
||||
pbr makes it possible to express them through static data files.
|
||||
|
||||
.. _setup_py:
|
||||
|
||||
setup.py
|
||||
--------
|
||||
|
||||
`pbr` only requires a minimal `setup.py` file compared to a standard setuptools
|
||||
project. This is because most configuration is located in static configuration
|
||||
files. This recommended minimal `setup.py` file should look something like this::
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from setuptools import setup
|
||||
|
||||
setup(
|
||||
setup_requires=['pbr'],
|
||||
pbr=True,
|
||||
)
|
||||
|
||||
.. note::
|
||||
|
||||
It is necessary to specify ``pbr=True`` to enabled `pbr` functionality.
|
||||
|
||||
.. note::
|
||||
|
||||
While one can pass any arguments supported by setuptools to `setup()`,
|
||||
any conflicting arguments supplied in `setup.cfg` will take precedence.
|
||||
|
||||
setup.cfg
|
||||
---------
|
||||
|
||||
The `setup.cfg` file is an ini-like file that can mostly replace the `setup.py`
|
||||
file. It is based on the distutils2_ `setup.cfg` file. A simple sample can be
|
||||
found in `pbr`'s own `setup.cfg` (it uses its own machinery to install
|
||||
itself)::
|
||||
|
||||
[metadata]
|
||||
name = pbr
|
||||
author = OpenStack Foundation
|
||||
author-email = openstack-dev@lists.openstack.org
|
||||
summary = OpenStack's setup automation in a reusable form
|
||||
description-file = README
|
||||
home-page = https://launchpad.net/pbr
|
||||
license = Apache-2
|
||||
classifier =
|
||||
Development Status :: 4 - Beta
|
||||
Environment :: Console
|
||||
Environment :: OpenStack
|
||||
Intended Audience :: Developers
|
||||
Intended Audience :: Information Technology
|
||||
License :: OSI Approved :: Apache Software License
|
||||
Operating System :: OS Independent
|
||||
Programming Language :: Python
|
||||
keywords =
|
||||
setup
|
||||
distutils
|
||||
|
||||
[files]
|
||||
packages =
|
||||
pbr
|
||||
data_files =
|
||||
etc/pbr = etc/*
|
||||
etc/init =
|
||||
pbr.packaging.conf
|
||||
pbr.version.conf
|
||||
|
||||
[entry_points]
|
||||
console_scripts =
|
||||
pbr = pbr.cmd:main
|
||||
pbr.config.drivers =
|
||||
plain = pbr.cfg.driver:Plain
|
||||
|
||||
`pbr` provides its own section in these documents, ostensibly called ``pbr``,
|
||||
and provides a custom version of Sphinx's ``build_sphinx`` section. Most other
|
||||
sections are provided by setuptools and may influence either the build itself
|
||||
or the output of various `setuptools commands`__. The remaining sections are
|
||||
provided by libraries that provide setuptools extensions, such as
|
||||
``extract_mesages`` (provided by `Babel`__). Some of these are described below.
|
||||
|
||||
__ https://setuptools.readthedocs.io/en/latest/setuptools.html#command-reference
|
||||
__ http://babel.pocoo.org/en/latest/setup.html
|
||||
__ http://www.sphinx-doc.org/en/stable/setuptools.html
|
||||
|
||||
.. note::
|
||||
|
||||
Comments may be used in `setup.cfg`, however all comments should start with
|
||||
a `#` and may be on a single line, or in line, with at least one white space
|
||||
character immediately preceding the `#`. Semicolons are not a supported
|
||||
comment delimiter. For instance::
|
||||
|
||||
[section]
|
||||
# A comment at the start of a dedicated line
|
||||
key =
|
||||
value1 # An in line comment
|
||||
value2
|
||||
# A comment on a dedicated line
|
||||
value3
|
||||
|
||||
files
|
||||
~~~~~
|
||||
|
||||
The ``files`` section defines the install location of files in the package
|
||||
using three fundamental keys: ``packages``, ``namespace_packages``, and
|
||||
``data_files``.
|
||||
|
||||
``packages``
|
||||
|
||||
A list of top-level packages that should be installed. The behavior of
|
||||
packages is similar to ``setuptools.find_packages`` in that it recurses the
|
||||
python package hierarchy below the given top level and installs all of it. If
|
||||
``packages`` is not specified, it defaults to the value of the ``name`` field
|
||||
given in the ``[metadata]`` section.
|
||||
|
||||
``namespace_packages``
|
||||
|
||||
Similar to ``packages``, but is a list of packages that provide namespace
|
||||
packages.
|
||||
|
||||
``data_files``
|
||||
|
||||
A list of files to be installed. The format is an indented block that
|
||||
contains key value pairs which specify target directory and source file to
|
||||
install there. More than one source file for a directory may be indicated
|
||||
with a further indented list. Source files are stripped of leading
|
||||
directories. Additionally, `pbr` supports a simple file globbing syntax for
|
||||
installing entire directory structures, thus::
|
||||
|
||||
[files]
|
||||
data_files =
|
||||
etc/pbr = etc/pbr/*
|
||||
etc/neutron =
|
||||
etc/api-paste.ini
|
||||
etc/dhcp-agent.ini
|
||||
etc/init.d = neutron.init
|
||||
|
||||
will result in `/etc/neutron` containing `api-paste.ini` and `dhcp-agent.ini`,
|
||||
both of which pbr will expect to find in the `etc` directory in the root of
|
||||
the source tree. Additionally, `neutron.init` from that dir will be installed
|
||||
in `/etc/init.d`. All of the files and directories located under `etc/pbr` in
|
||||
the source tree will be installed into `/etc/pbr`.
|
||||
|
||||
Note that this behavior is relative to the effective root of the environment
|
||||
into which the packages are installed, so depending on available permissions
|
||||
this could be the actual system-wide `/etc` directory or just a top-level
|
||||
`etc` subdirectory of a virtualenv.
|
||||
|
||||
pbr
|
||||
~~~
|
||||
|
||||
The ``pbr`` section controls `pbr` specific options and behaviours.
|
||||
|
||||
``autodoc_tree_index_modules``
|
||||
|
||||
A boolean option controlling whether `pbr` should generate an index of
|
||||
modules using `sphinx-apidoc`. By default, all files except `setup.py` are
|
||||
included, but this can be overridden using the ``autodoc_tree_excludes``
|
||||
option.
|
||||
|
||||
``autodoc_tree_excludes``
|
||||
|
||||
A list of modules to exclude when building documentation using
|
||||
`sphinx-apidoc`. Defaults to ``[setup.py]``. Refer to the `sphinx-apidoc man
|
||||
page`_ for more information.
|
||||
|
||||
``autodoc_index_modules``
|
||||
|
||||
A boolean option controlling whether `pbr` should itself generates
|
||||
documentation for Python modules of the project. By default, all found Python
|
||||
modules are included; some of them can be excluded by listing them in
|
||||
``autodoc_exclude_modules``.
|
||||
|
||||
``autodoc_exclude_modules``
|
||||
|
||||
A list of modules to exclude when building module documentation using `pbr`.
|
||||
`fnmatch` style pattern (e.g. `myapp.tests.*`) can be used.
|
||||
|
||||
``api_doc_dir``
|
||||
|
||||
A subdirectory inside the ``build_sphinx.source_dir`` where
|
||||
auto-generated API documentation should be written, if
|
||||
``autodoc_index_modules`` is set to True. Defaults to ``"api"``.
|
||||
|
||||
.. note::
|
||||
|
||||
When using ``autodoc_tree_excludes`` or ``autodoc_index_modules`` you may
|
||||
also need to set ``exclude_patterns`` in your Sphinx configuration file
|
||||
(generally found at `doc/source/conf.py` in most OpenStack projects)
|
||||
otherwise Sphinx may complain about documents that are not in a toctree.
|
||||
This is especially true if the ``[sphinx_build] warning-is-error`` option is
|
||||
set. See the `Sphinx build configuration file`_ documentation for more
|
||||
information on configuring Sphinx.
|
||||
|
||||
.. versionchanged:: 2.0
|
||||
|
||||
The ``pbr`` section used to take a ``warnerrors`` option that would enable
|
||||
the ``-W`` (Turn warnings into errors.) option when building Sphinx. This
|
||||
feature was broken in 1.10 and was removed in pbr 2.0 in favour of the
|
||||
``[build_sphinx] warning-is-error`` provided in Sphinx 1.5+.
|
||||
|
||||
build_sphinx
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The ``build_sphinx`` section is a version of the ``build_sphinx`` setuptools
|
||||
plugin provided with Sphinx. This plugin extends the original plugin to add the
|
||||
following:
|
||||
|
||||
- Automatic generation of module documentation using the apidoc__ tool
|
||||
|
||||
- Automatic configuration of the `project`, `version` and `release` settings
|
||||
using information from `pbr` itself
|
||||
|
||||
- Support for multiple builders using the ``builders`` configuration option
|
||||
|
||||
.. note::
|
||||
|
||||
Sphinx 1.6 adds support for multiple builders using the default `builder`
|
||||
option. You should refer to this file for more information.
|
||||
|
||||
The version of ``build_sphinx`` provided by `pbr` provides a single additional
|
||||
option.
|
||||
|
||||
``builders``
|
||||
|
||||
A space or comma separated list of builders to run. For example, to build
|
||||
both HTML and man page documentation, you would define the following in your
|
||||
`setup.cfg`:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[build_sphinx]
|
||||
builders = html,man
|
||||
source-dir = doc/source
|
||||
build-dir = doc/build
|
||||
all-files = 1
|
||||
|
||||
``source_dir``
|
||||
|
||||
The path to the source directory where the Sphinx documentation tree
|
||||
is.
|
||||
|
||||
For information on the remaining options, refer to the `Sphinx
|
||||
documentation`__. In addition, the ``autodoc_index_modules``,
|
||||
``autodoc_tree_index_modules``, ``autodoc_exclude_modules`` and
|
||||
``autodoc_tree_excludes`` options in the ``pbr`` section will affect the output
|
||||
of the automatic module documentation generation.
|
||||
|
||||
.. versionchanged:: 3.0
|
||||
|
||||
The ``build_sphinx`` plugin used to default to building both HTML and man
|
||||
page output. This is no longer the case, and you should explicitly set
|
||||
``builders`` to ``html man`` if you wish to retain this behavior.
|
||||
|
||||
__ http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html
|
||||
__ http://www.sphinx-doc.org/en/stable/setuptools.html
|
||||
|
||||
entry_points
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The ``entry_points`` section defines entry points for generated console scripts
|
||||
and python libraries. This is actually provided by `setuptools`__ but is
|
||||
documented here owing to its importance.
|
||||
|
||||
The general syntax of specifying entry points is a top level name indicating
|
||||
the entry point group name, followed by one or more key value pairs naming
|
||||
the entry point to be installed. For instance::
|
||||
|
||||
[entry_points]
|
||||
console_scripts =
|
||||
pbr = pbr.cmd:main
|
||||
pbr.config.drivers =
|
||||
plain = pbr.cfg.driver:Plain
|
||||
fancy = pbr.cfg.driver:Fancy
|
||||
|
||||
Will cause a console script called `pbr` to be installed that executes the
|
||||
`main` function found in `pbr.cmd`. Additionally, two entry points will be
|
||||
installed for `pbr.config.drivers`, one called `plain` which maps to the
|
||||
`Plain` class in `pbr.cfg.driver` and one called `fancy` which maps to the
|
||||
`Fancy` class in `pbr.cfg.driver`.
|
||||
|
||||
__ https://setuptools.readthedocs.io/en/latest/setuptools.html#options
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
Requirement files should be given one of the below names. This order is also
|
||||
the order that the requirements are tried in (where `N` is the Python major
|
||||
version number used to install the package):
|
||||
|
||||
* requirements-pyN.txt
|
||||
* tools/pip-requires-py3
|
||||
* requirements.txt
|
||||
* tools/pip-requires
|
||||
|
||||
Only the first file found is used to install the list of packages it contains.
|
||||
|
||||
.. note::
|
||||
|
||||
The 'requirements-pyN.txt' file is deprecated - 'requirements.txt' should
|
||||
be universal. You can use `Environment markers`_ for this purpose.
|
||||
|
||||
Extra requirements
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Groups of optional dependencies, or `"extra" requirements`_, can be described
|
||||
in your `setup.cfg`, rather than needing to be added to `setup.py`. An example
|
||||
(which also demonstrates the use of environment markers) is shown below.
|
||||
|
||||
Environment markers
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Environment markers are `conditional dependencies`_ which can be added to the
|
||||
requirements (or to a group of extra requirements) automatically, depending
|
||||
on the environment the installer is running in. They can be added to
|
||||
requirements in the requirements file, or to extras defined in `setup.cfg`,
|
||||
but the format is slightly different for each.
|
||||
|
||||
For ``requirements.txt``::
|
||||
|
||||
argparse; python_version=='2.6'
|
||||
|
||||
This will result in the package depending on ``argparse`` only if it's being
|
||||
installed into Python 2.6
|
||||
|
||||
For extras specified in `setup.cfg`, add an ``extras`` section. For instance,
|
||||
to create two groups of extra requirements with additional constraints on the
|
||||
environment, you can use::
|
||||
|
||||
[extras]
|
||||
security =
|
||||
aleph
|
||||
bet:python_version=='3.2'
|
||||
gimel:python_version=='2.7'
|
||||
testing =
|
||||
quux:python_version=='2.7'
|
||||
|
||||
|
||||
Testing
|
||||
-------
|
||||
|
||||
`pbr` overrides the ``setuptools`` hook ``test`` (i.e. ``setup.py test``). The
|
||||
following sequence is followed:
|
||||
|
||||
#. If a ``.testr.conf`` file exists and `testrepository
|
||||
<https://pypi.python.org/pypi/testrepository>`__ is installed, `pbr`
|
||||
will use it as the test runner. See the ``testr`` documentation
|
||||
for more details.
|
||||
|
||||
.. note::
|
||||
|
||||
This is separate to ``setup.py testr`` (note the extra ``r``) which
|
||||
is provided directly by the ``testrepository`` package. Be careful
|
||||
as there is some overlap of command arguments.
|
||||
|
||||
#. Although deprecated, if ``[nosetests]`` is defined in ``setup.cfg``
|
||||
and `nose <http://nose.readthedocs.io/en/latest/>`__ is installed,
|
||||
the ``nose`` runner will be used.
|
||||
|
||||
#. In other cases no override will be installed and the ``test``
|
||||
command will revert to `setuptools
|
||||
<http://setuptools.readthedocs.io/en/latest/setuptools.html#test-build-package-and-run-a-unittest-suite>`__.
|
||||
|
||||
A typical usage would be in ``tox.ini`` such as::
|
||||
|
||||
[tox]
|
||||
minversion = 2.0
|
||||
skipsdist = True
|
||||
envlist = py33,py34,py35,py26,py27,pypy,pep8,docs
|
||||
|
||||
[testenv]
|
||||
usedevelop = True
|
||||
setenv =
|
||||
VIRTUAL_ENV={envdir}
|
||||
CLIENT_NAME=pbr
|
||||
deps = .
|
||||
-r{toxinidir}/test-requirements.txt
|
||||
commands =
|
||||
python setup.py test --testr-args='{posargs}'
|
||||
|
||||
The argument ``--coverage`` will set ``PYTHON`` to ``coverage run`` to
|
||||
produce a coverage report. ``--coverage-package-name`` can be used to
|
||||
modify or narrow the packages traced.
|
||||
|
||||
.. _d2to1: https://pypi.python.org/pypi/d2to1
|
||||
.. _distutils2: https://pypi.python.org/pypi/Distutils2
|
||||
.. _PEP 426: http://legacy.python.org/dev/peps/pep-0426/
|
||||
.. _OpenStack: https://www.openstack.org/
|
Loading…
Reference in New Issue