diff --git a/README.rst b/README.rst index ecdbb9aa..e7a13116 100644 --- a/README.rst +++ b/README.rst @@ -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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 266988a0..018b800b 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 ================== diff --git a/setup.cfg b/setup.cfg index 87e820b9..efd34891 100644 --- a/setup.cfg +++ b/setup.cfg @@ -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