Update documentation for release.0.5.0

Change-Id: I215bfa00a836c7fafb535b78e6fef89c81e28817

1 files changed, 67 insertions, 5 deletions

diff --git a/README.rst b/README.rst
index 8a2eb62..146fa40 100644
--- a/README.rst
+++ b/README.rst
@@ -1,26 +1,88 @@
 Introduction
 ============
 
-pbr provides a set of default python packaging configuration and
-behaviors. It is implemented as a setup hook for d2to1 which allows us to
-manipulate the setup.cfg information before it is passed to setup.py.
+PBR is a library that injects some useful and sensible default behaviors
+into your setuptools run. It started off life as the chunks of code that
+were copied between all of the OpenStack projects. Around the time that
+OpenStack hit 18 different projects each with at least 3 active branches,
+it seems like a good time to make that code into a proper re-usable library.
+
+PBR is only mildly configurable. The basic idea is that there's a decent
+way to run things and if you do, you should reap the rewards, because then
+it's simple and repeatable. If you want to do things differently, cool! But
+you've already got the power of python at your fingertips, so you don't
+really need PBR.
+
+PBR builds on top of `d2to1` to provide for declarative configuration. It
+then filters the `setup.cfg` data through a setup hook to fill in default
+values and provide more sensible behaviors.
 
 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.
 
-requirements.txt and test-requirements.txt will be used to populate
-install requirements as needed.
+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