Merge "Add more documentation"

3 files changed, 188 insertions, 124 deletions

diff --git a/README.rst b/README.rst
index ecdbb9a..e7a1311 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 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
 ==================
diff --git a/setup.cfg b/setup.cfg
index 87e820b..efd3489 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