Add more documentation

Moved a good portion of README into the sphinx docs. Also started
fleshing out descriptions of how to use things. Also, fix the sphinx
config.

Change-Id: If53dcdaea0a48ef613e3097ab55d34f056160188
This commit is contained in:
Monty Taylor 2013-07-17 09:12:45 -07:00
parent c84876dc0f
commit 904f79c867
3 changed files with 188 additions and 124 deletions

View File

@ -22,127 +22,6 @@ when that library itself will alter how the setup is processed. As Metadata
2.0 and other modern Python packaging PEPs come out, `pbr` aims to support
them as quickly as possible.
`pbr` reads and then filters the `setup.cfg` data through a setup hook to
fill in default values and provide more sensible behaviors, and then feeds
the results in as the arguments to a call to `setup.py` - so the heavy
lifting of handling python packaging needs is still being done by
`setuptools`.
Behaviors
=========
What It Does
------------
PBR can and does do a bunch of things for you:
* **Version**: Manage version number bad on git revisions and tags
* **AUTHORS**: Generate AUTHORS file from git log
* **ChangeLog**: Generate ChangeLog from git log
* **Sphinx Autodoc**: Generate autodoc stub files for your whole module
* **Requirements**: Store your dependencies in a pip requirements file
* **long_description**: Use your README file as a long_description
* **Smart find_packages**: Smartly find packages under your root package
Version
^^^^^^^
Version strings will be inferred from git. If a given revision is tagged,
that's the version. If it's not, and you don't provide a version, the version
will be very similar to git describe. If you do, then we'll assume that's the
version you are working towards, and will generate alpha version strings
based on commits since last tag and the current git sha.
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.
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.
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
popuplate a virtualenv for testing, or to just install everything you need.
Duplicating the information, though, is super lame. So PBR will let you
keep requirements.txt format files around describing the requirements for
your project, will parse them and split them up approprirately, and inject
them into the install_requires and/or tests_require and/or dependency_links
arguments to setup. Voila!
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 requires a distribution to use distribute. Your distribution
must include a distutils2-like setup.cfg file, and a minimal setup.py script.
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 reuable form
description-file = README
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 =
oslo
The minimal setup.py should look something like this::
#!/usr/bin/env python
from setuptools import setup
setup(
setup_requires=['pbr'],
pbr=True,
)
Note that it's important to specify `pbr=True` or else the pbr functionality
will not be enabled.
It should also work fine if additional arguments are passed to `setup()`,
but it should be noted that they will be clobbered by any options in the
setup.cfg file.
Running Tests
=============
The testing system is based on a combination of tox and testr. The canonical

View File

@ -1,9 +1,189 @@
pbr - Python Build Reasonableness
=================================
===================================
pbr - Python Build Reasonableness
===================================
A library for managing setuptools packaging needs in a consistent manner.
PBR is not a library about beer.
`pbr` reads and then filters the `setup.cfg` data through a setup hook to
fill in default values and provide more sensible behaviors, and then feeds
the results in as the arguments to a call to `setup.py` - so the heavy
lifting of handling python packaging needs is still being done by
`setuptools`.
What It Does
============
PBR can and does do a bunch of things for you:
* **Version**: Manage version number based on git revisions and tags
* **AUTHORS**: Generate AUTHORS file from git log
* **ChangeLog**: Generate ChangeLog from git log
* **Sphinx Autodoc**: Generate autodoc stub files for your whole module
* **Requirements**: Store your dependencies in a pip requirements file
* **long_description**: Use your README file as a long_description
* **Smart find_packages**: Smartly find packages under your root package
Version
-------
Version strings will be inferred from git. If a given revision is tagged,
that's the version. If it's not, and you don't provide a version, the version
will be very similar to git describe. If you do, then we'll assume that's the
version you are working towards, and will generate alpha version strings
based on commits since last tag and the current git sha.
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.
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.
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
popuplate a virtualenv for testing, or to just install everything you need.
Duplicating the information, though, is super lame. So PBR will let you
keep requirements.txt format files around describing the requirements for
your project, will parse them and split them up approprirately, and inject
them into the install_requires and/or tests_require and/or dependency_links
arguments to setup. Voila!
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 requires a distribution to use distribute. Your distribution
must include a distutils2-like setup.cfg file, and a minimal setup.py script.
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 reuable form
description-file = README
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/init =
pbr.packaging.conf
pbr.version.conf
[entry_points]
console_scripts =
pbr = pbr.cmd:main
pbr.config.drivers =
plain = pbr.cfg.driver:Plain
The minimal setup.py should look something like this::
#!/usr/bin/env python
from setuptools import setup
setup(
setup_requires=['pbr'],
pbr=True,
)
Note that it's important to specify `pbr=True` or else the pbr functionality
will not be enabled.
It should also work fine if additional arguments are passed to `setup()`,
but it should be noted that they will be clobbered by any options in the
setup.cfg file.
files
-----
The format of the files section is worth explaining. There are three
fundamental keys one is likely to care about, `packages`,
`namespace_packages`, and `data_files`.
`packages` is 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 heirarchy below the given top level and installs
all of it. If `packages` is not specified, it defaults to the name given
in the `[metadata]` section.
`namespace_packages` is the same, but is a list of packages that provide
namespace packages.
`data_files` lists 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, so::
[files]
data_files =
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`.
entry_points
------------
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`.
Indices and tables
==================

View File

@ -31,3 +31,8 @@ warnerrors = True
[entry_points]
distutils.setup_keywords =
pbr = pbr.core:pbr
[build_sphinx]
all_files = 1
build-dir = doc/build
source-dir = doc/source