Commit dcc0c601 authored by Jim Fulton's avatar Jim Fulton Committed by GitHub

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!
parent 410951b5
This diff is collapsed.
This diff is collapsed.
...@@ -56,45 +56,4 @@ Buildout is a project designed to solve 2 problems: ...@@ -56,45 +56,4 @@ Buildout is a project designed to solve 2 problems:
distribution, there can only be one installed. distribution, there can only be one installed.
To learn more about buildout, including how to use it, see To learn more about buildout, including how to use it, see
http://buildout.org/. http://docs.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
...@@ -75,3 +75,21 @@ Learn more: ...@@ -75,3 +75,21 @@ Learn more:
- :doc:`Reference <reference>` - :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>`_.
...@@ -63,6 +63,8 @@ Buildout command-line options ...@@ -63,6 +63,8 @@ Buildout command-line options
``-U`` ``-U``
Don't use :ref:`user-default configuration <user-default-configuration>`. Don't use :ref:`user-default configuration <user-default-configuration>`.
.. _verbosity-level:
``-v`` ``-v``
Increase the level of verbosity. This option can be used multiple Increase the level of verbosity. This option can be used multiple
times. times.
......
===================
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>`_.
...@@ -10,6 +10,7 @@ Buildout Topics ...@@ -10,6 +10,7 @@ Buildout Topics
implicit-parts implicit-parts
optimizing optimizing
bootstrapping bootstrapping
extensions
writing-recipes writing-recipes
meta-recipes meta-recipes
......
...@@ -342,6 +342,20 @@ entry points, using the type ``zc.buildout.uninstall`` as can be seen ...@@ -342,6 +342,20 @@ entry points, using the type ``zc.buildout.uninstall`` as can be seen
in the `zc.recipe.rhrc setup script in the `zc.recipe.rhrc setup script
<https://github.com/zopefoundation/zc.recipe.rhrc/blob/master/setup.py#L23>`_. <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 Testing recipes
================ ================
...@@ -602,7 +616,6 @@ do that by looking at the `source of this topic ...@@ -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. Otherwise, it's very easy to end up with mistakes in your examples.
.. [#installed] Configuration data from previous runs are saved in a .. [#installed] Configuration data from previous runs are saved in a
buildout's installed database, :ref:`typically saved in buildout's installed database, :ref:`typically saved in
<installed-option>` a generated ``.installed.cfg`` file. <installed-option>` a generated ``.installed.cfg`` file.
......
...@@ -20,48 +20,7 @@ from setuptools import setup ...@@ -20,48 +20,7 @@ from setuptools import setup
def read(*rnames): def read(*rnames):
return open(os.path.join(os.path.dirname(__file__), *rnames)).read() return open(os.path.join(os.path.dirname(__file__), *rnames)).read()
doc_intro = """ long_description= read('README.rst') + '\n' + read('CHANGES.rst')
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'
)
entry_points = """ entry_points = """
[console_scripts] [console_scripts]
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment