Added topic on reusing option values and buildout config options reference (#347)

* Added topic on reusing option values and buildout config options reference

* unbroke capitalization

* added another todo

But maybe I should stop doing this because sphinx tells me about
missing references.

* note that paths are whitespace separated.

* fixed some minor wording bugs.

* Added a hidden test to check my understanding of interaction with install-from-cache

* Clarify modes and semantics of extends-cache

* emphasize that in newst mode, we always download configuration

* expanded on logging control

* clarified socket-timeout

* spelling and it's

* simplify user-default example

* warn about unpinning when using develop eggs

* discuss unpinning

* explain why unpinning with empty pin is useful.

* reverted examples to use longer more explict forms

* typos

* Added tests for variables-extending-and-substitutions.rst

Also added more test helpers.

doc/getting-started.rst

@@ -56,7 +56,6 @@ with a parts option.  If we run Buildout:
    >>> run_buildout(src)
 
    >>> import os
-   >>> ls = lambda d='.': os.listdir(d)
    >>> eqs(ls(), 'buildout.cfg', 'bin', 'eggs', 'develop-eggs', 'parts', 'out')
 
    >>> eqs(ls('bin'))
@@ -403,6 +402,8 @@ Buildout to *not* check for newer versions of Python requirements:
 This relaxes repeatability, but with little risk if there was a recent
 run without this option.
 
+.. _pinned-versions:
+
 Pinned versions
 _______________
 
@@ -567,6 +568,30 @@ that your component only works a range of versions of some dependency,
 the express the range in your project requirements. Don't require
 specific versions.
 
+.. _unpinning-versions:
+
+Unpinning versions
+__________________
+
+You can unpin a version by just removing it (or commenting it out of)
+your ``versions`` section.
+
+You can also unpin a version by setting the version to an empty
+string:
+
+.. code-block:: ini
+
+  [versions]
+  ZEO =
+
+In an extending configuration (``buildout.cfg`` in the example above), or
+:ref:`on the buildout command line <unpinning-on-command-line>`.
+
+You might do this if pins are shared between projects and you want to
+unpin a requirement for one of the projects, or want to remove a pin
+while using a requirement in :ref:`development mode
+<python-development-projects>`.
+
 Buildout versions and automatic upgrade
 ---------------------------------------
 
@@ -602,6 +627,8 @@ Then Buildout will upgrade or downgrade to be consistent with version
 requirements.  See the :doc:`bootstrapping topic
 <topics/bootstrapping>` to learn more about bootstrapping.
 
+.. _python-development-projects:
+
 Python development projects
 ===========================
 

doc/topics/history.rst

@@ -70,6 +70,8 @@ To achieve Buildout's goals, it was necessary to interact with
 setuptools at a much lower level and to write quite a bit more
 packaging logic than planned.
 
+.. _eggs-label:
+
 Eggs
 ----
 

doc/topics/index.rst

@@ -6,9 +6,11 @@ Buildout Topics
    :maxdepth: 2
 
    history
+   variables-extending-and-substitutions
    bootstrapping
 
 .. todo:
 
-   variables-extending-and-substitutions
    writing-recipes
+   optimizing
+

src/zc/buildout/extends-cache.txt

@@ -107,6 +107,11 @@ base.cfg from the cache:
 >>> print_(system(buildout + ' -o'))
 Unused options for buildout: 'foo'.
 
+.. verify same behavior for install-from-cache:
+
+   >>> print_(system(buildout + ' install-from-cache=true download-cache=.'))
+   Unused options for buildout: 'foo'.
+
 In online mode, buildout will download and use the modified version:
 
 >>> print_(system(buildout))

src/zc/buildout/tests.py

@@ -3455,7 +3455,8 @@ normalize_S = (
     )
 
 def run_buildout(command):
-    os.environ['HOME'] = os.getcwd() # Make sure we don't get .buildout
+    # Make sure we don't get .buildout
+    os.environ['HOME'] = os.path.join(os.getcwd(), 'home')
     args = command.strip().split()
     import pkg_resources
     buildout = pkg_resources.load_entry_point(
@@ -3751,18 +3752,32 @@ def test_suite():
                 with open(path) as f:
                     return f.read()
 
-            def write(text, path):
-                with open(path, 'w') as f:
+            def write(text, *path):
+                with open(os.path.join(*path), 'w') as f:
                     f.write(text)
 
+            def eqs(a, *b):
+                a = set(a); b = set(b)
+                return None if a == b else (a - b, b - a)
+
+            def clear_here():
+                for name in os.listdir('.'):
+                    if os.path.isfile(name):
+                        os.remove(name)
+                    else:
+                        shutil.rmtree(name)
+
             test.globs.update(
                 run_buildout=run_buildout_in_process,
                 yup=lambda cond, orelse='Nope': None if cond else orelse,
                 nope=lambda cond, orelse='Nope': orelse if cond else None,
                 eq=lambda a, b: None if a == b else (a, b),
-                eqs=lambda a, *b: None if set(a) == set(b) else (a, b),
+                eqs=eqs,
                 read=read,
                 write=write,
+                ls=lambda d='.', *rest: os.listdir(os.path.join(d, *rest)),
+                join=os.path.join,
+                clear_here=clear_here
                 )
             setupstack.setUpDirectory(test)
 
@@ -3771,6 +3786,9 @@ def test_suite():
                 manuel.doctest.Manuel() + manuel.capture.Manuel(),
                 os.path.join(docdir, 'getting-started.rst'),
                 os.path.join(docdir, 'topics', 'bootstrapping.rst'),
+                os.path.join(
+                    docdir,
+                    'topics', 'variables-extending-and-substitutions.rst'),
                 setUp=docSetUp, tearDown=setupstack.tearDown
                 ))