Last minute details and cur over to new docs (#374)

* Document UserError

* Additional resources.

* briefly explain extensions

Later, we'll probably discuss how to develop them, probably in a separate document.

* move old changes to HISTORY.rst

* Cut over to new docs!

README.rst

@@ -56,45 +56,4 @@ Buildout is a project designed to solve 2 problems:
    distribution, there can only be one installed.
 
 To learn more about buildout, including how to use it, see
-http://buildout.org/.
-
-
-Installation
-************
-
-There are a number of ways to install buildout.  You can install it as
-you would any other package, using pip or easy_install.  In this case,
-you'll get a buildout command that you can use to build projects.  To
-build a project, just use::
-
-  buildout
-
-from a project directory.
-
-Buildout's (stubborn) philosophy, however, is that projects should be
-self-contained, and not require changes to a shared Python
-installation. To avoid changing a shared Python installation you can
-download a bootstrap script that, when run, will install buildout
-locally in your project.
-
-The bootstrap script for buildout version 2 is at:
-
-  https://bootstrap.pypa.io/bootstrap-buildout.py
-
-So, for example, to install buildout 2 in a project, you might::
-
-  wget https://bootstrap.pypa.io/bootstrap-buildout.py
-  python bootstrap-buildout.py
-
-Then to build your project, you can just run::
-
-  bin/buildout
-
-from the project directory.
-
-buildout 2 is somewhat backward-incompatible with version 1.  Most
-projects will probably work fine with either.  If you need to keep
-using version 1, however, specify a version requirement when you use
-pip or easy_install, or use the version 1 bootstrap script at:
-
-  http://downloads.buildout.org/1/bootstrap.py
+http://docs.buildout.org/.

doc/index.rst

@@ -75,3 +75,21 @@ Learn more:
 - :doc:`Reference <reference>`
 
 
+Additional resources
+====================
+
+Issue tracker
+  https://github.com/buildout/buildout/issues
+
+Mailing list
+  You can ask questions on the Python Distutils-SIG
+  mailing list, https://mail.python.org/mailman/listinfo/distutils-sig
+
+Github repository
+  https://github.com/buildout/buildout
+
+Contributing
+  Join the buildout-development google group,
+  https://groups.google.com/forum/#!forum/buildout-development to
+  discuss ideas and submit pull requests against the `buildout
+  repository <https://github.com/buildout/buildout>`_.

doc/reference.rst

@@ -63,6 +63,8 @@ Buildout command-line options
 ``-U``
   Don't use :ref:`user-default configuration <user-default-configuration>`.
 
+.. _verbosity-level:
+
 ``-v``
   Increase the level of verbosity.  This option can be used multiple
   times.

doc/topics/extensions.rst

+===================
+Buildout extensions
+===================
+
+Buildout has a mechanism that can be used to extend it in low-level
+and often experimental ways.  Use the ``extensions`` option in the
+``buildout`` section to use an existing extension. For example, the
+`buildout.wheel extension
+<https://github.com/buildout/buildout.wheel>`_ provides support for
+`Python wheels <http://pythonwheels.com/>`_:
+
+.. code-block:: ini
+
+  [buildout]
+  extensions = buildout.wheel
+  ...
+
+Some other examples of extensions can be found in the `standard
+package index <https://pypi.python.org/pypi?:action=browse&c=512&c=546>`_.

doc/topics/index.rst

@@ -10,6 +10,7 @@ Buildout Topics
    implicit-parts
    optimizing
    bootstrapping
+   extensions
    writing-recipes
    meta-recipes
 

doc/topics/writing-recipes.rst

@@ -342,6 +342,20 @@ entry points, using the type ``zc.buildout.uninstall`` as can be seen
 in the `zc.recipe.rhrc setup script
 <https://github.com/zopefoundation/zc.recipe.rhrc/blob/master/setup.py#L23>`_.
 
+User interaction: logging and UserError
+=======================================
+
+Recipes communicate to users through logging and errors. Recipes can
+log information using the Python logging library and messages will be
+displayed according to buildout's :ref:`verbosity setting <verbosity-level>`.
+
+Errors that a user can potentially correct should be reported by
+raising ``zc.buildout.UserError`` exceptions with error messages as
+arguments.
+
+Buildout will display these as user errors, rather than printing a
+trace back.
+
 Testing recipes
 ================
 
@@ -602,7 +616,6 @@ do that by looking at the `source of this topic
 Otherwise, it's very easy to end up with mistakes in your examples.
 
 
-
 .. [#installed] Configuration data from previous runs are saved in a
    buildout's installed database, :ref:`typically saved in
    <installed-option>` a generated ``.installed.cfg`` file.

setup.py

@@ -20,48 +20,7 @@ from setuptools import setup
 def read(*rnames):
     return open(os.path.join(os.path.dirname(__file__), *rnames)).read()
 
-doc_intro = """
-
-Below, you'll find doctest-based documentation.  It was an experiment
-in reusing tests as documentation.  The experiment didn't go that
-well, but there may be details below that aren't easy to find on
-buildout.org yet.
-
-.. contents ::
-
-doctest-based Documentation
-***************************
-
-"""
-
-long_description=(
-        read('README.rst')
-        + doc_intro +
-        read('src', 'zc', 'buildout', 'buildout.txt')
-        + '\n' +
-        read('src', 'zc', 'buildout', 'repeatable.txt')
-        + '\n' +
-        read('src', 'zc', 'buildout', 'download.txt')
-        + '\n' +
-        read('src', 'zc', 'buildout', 'downloadcache.txt')
-        + '\n' +
-        read('src', 'zc', 'buildout', 'extends-cache.txt')
-        + '\n' +
-        read('src', 'zc', 'buildout', 'setup.txt')
-        + '\n' +
-        read('src', 'zc', 'buildout', 'update.txt')
-        + '\n' +
-        read('src', 'zc', 'buildout', 'debugging.txt')
-        + '\n' +
-        read('src', 'zc', 'buildout', 'testing.txt')
-        + '\n' +
-        read('src', 'zc', 'buildout', 'easy_install.txt')
-        + '\n' +
-        read('CHANGES.rst')
-        # + '\n' +
-        # 'Download\n'
-        # '**********************\n'
-        )
+long_description= read('README.rst') + '\n' + read('CHANGES.rst')
 
 entry_points = """
 [console_scripts]