diff options
Diffstat (limited to 'doc/source/index.rst')
| -rw-r--r-- | doc/source/index.rst | 186 |
1 files changed, 183 insertions, 3 deletions
diff --git a/doc/source/index.rst b/doc/source/index.rst index 266988a..018b800 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 ================== |