Added the writing-recipes topic (#359)

doc/reference.rst

@@ -138,6 +138,22 @@ It then runs the resulting buildout.
 
 See :ref:`Bootstrapping <init-generates-buildout.cfg>` for examples.
 
+.. _install-command:
+
+install
+_______
+
+Install the parts specified in the buildout configuration.  This is
+the default command if no command is specified.
+
+.. We're not documenting arguments.
+
+   Passing arguments to install is an attractive nuisance, since it
+   can lead to parts being installed inconsistently.  The feature
+   exists for backward compatibility, but may be dropped in the
+   future.
+
+
 setup PATH SETUP-COMMANDS
 _________________________
 
@@ -301,6 +317,8 @@ extends-cache
   substitutions, and the result is a relative path, then it will be
   interpreted relative to the buildout directory.)
 
+.. _find-links-option:
+
 find-links, default: ''
   Extra locations to search for distributions to download.
 
@@ -337,6 +355,8 @@ install-from-cache, default: 'false'
   This mode may only be used if a :ref:`download-cache
   <download-cache>` is specified.
 
+.. _installed-option:
+
 installed, default: '.installed.cfg'
   The name of the file used to store information about what's installed.
 

doc/topics/index.rst

@@ -9,8 +9,6 @@ Buildout Topics
    variables-extending-and-substitutions
    optimizing
    bootstrapping
-
-.. todo:
-
    writing-recipes
 
+.. todo:

src/zc/buildout/buildout.py

@@ -1829,17 +1829,10 @@ Options and assignments can be interspersed.
 
 Commands:
 
-  install [parts]
+  install
 
-    Install parts.  If no command arguments are given, then the parts
-    definition from the configuration file is used.  Otherwise, the
-    arguments specify the parts to be installed.
-
-    Note that the semantics differ depending on whether any parts are
-    specified.  If parts are specified, then only those parts will be
-    installed. If no parts are specified, then the parts specified by
-    the buildout parts option will be installed along with all of
-    their dependencies.
+    Install the parts specified in the buildout configuration.  This is
+    the default command if no command is specified.
 
   bootstrap
 
@@ -1847,12 +1840,17 @@ Commands:
     the buildout and setuptools eggs and, creating a basic directory
     structure and a buildout-local buildout script.
 
-  init
+  init [requirements]
 
-    Initialize a buildout, creating a buildout.cfg file if it doesn't
-    exist and then performing the same actions as for the buildout
+    Initialize a buildout, creating a minimal buildout.cfg file if it doesn't
+    exist and then performing the same actions as for the bootstrap
     command.
 
+    If requirements are supplied, then the generated configuration
+    will include an interpreter script that requires them.  This
+    provides an easy way to quickly set up a buildout to experiment
+    with some packages.
+
   setup script [setup command and options]
 
     Run a given setup script arranging that setuptools is in the

src/zc/buildout/tests.py

@@ -3760,8 +3760,8 @@ def test_suite():
                 if process.is_alive() or process.exitcode:
                     print(read())
 
-            def read(path='out'):
-                with open(path) as f:
+            def read(path='out', *rest):
+                with open(os.path.join(path, *rest)) as f:
                     return f.read()
 
             def write(text, *path):
@@ -3789,7 +3789,8 @@ def test_suite():
                 write=write,
                 ls=lambda d='.', *rest: os.listdir(os.path.join(d, *rest)),
                 join=os.path.join,
-                clear_here=clear_here
+                clear_here=clear_here,
+                os=os,
                 )
             setupstack.setUpDirectory(test)
 
@@ -3802,6 +3803,7 @@ def test_suite():
                 os.path.join(
                     docdir,
                     'topics', 'variables-extending-and-substitutions.rst'),
+                os.path.join(docdir, 'topics', 'writing-recipes.rst'),
                 os.path.join(docdir, 'topics', 'optimizing.rst'),
                 setUp=docSetUp, tearDown=setupstack.tearDown
                 ))