Merge pull request #337 from buildout/getting-started

draft getting started

doc/contents.rst

@@ -12,6 +12,7 @@ Contents:
    :maxdepth: 2
 
    index
+   getting-started
    topics/index
    reference
 

doc/topics/index.rst

@@ -6,3 +6,8 @@ Buildout Topics
    :maxdepth: 2
 
 .. todo:
+
+   variables-extending-and-substitutions
+   writing-recipes
+   bootstrapping
+   buildout-and-packaging

setup.py

@@ -92,7 +92,8 @@ setup(
     ],
     include_package_data = True,
     entry_points = entry_points,
-    extras_require = dict(test=['zope.testing', 'manuel']),
+    extras_require = dict(
+        test=['zope.testing', 'manuel', 'ZEO ==4.3.1', 'zc.zdaemonrecipe']),
     zip_safe=False,
     classifiers = [
        'Intended Audience :: Developers',

src/zc/buildout/testing.py

@@ -212,6 +212,9 @@ def buildoutSetUp(test):
             root_logger.removeHandler(handler)
         for handler in handlers_before_set_up:
             root_logger.addHandler(handler)
+        bo_logger = logging.getLogger('zc.buildout')
+        for handler in bo_logger.handlers[:]:
+            bo_logger.removeHandler(handler)
     register_teardown(restore_root_logger_handlers)
 
     base = tempfile.mkdtemp('buildoutSetUp')

src/zc/buildout/tests.py

@@ -13,12 +13,13 @@
 #
 ##############################################################################
 from zc.buildout.buildout import print_
-from zope.testing import renormalizing
+from zope.testing import renormalizing, setupstack
 
 import doctest
 import manuel.capture
 import manuel.doctest
 import manuel.testing
+from multiprocessing import Process
 import os
 import pkg_resources
 import re
@@ -3422,10 +3423,14 @@ def updateSetup(test):
         makeNewRelease(dist.key, ws, new_releases)
         os.mkdir(os.path.join(new_releases, dist.key))
 
-bootstrap_py = os.path.join(
-    os.path.dirname(os.path.dirname(os.path.dirname(
-        os.path.dirname(__file__)))),
-    'bootstrap', 'bootstrap.py')
+def ancestor(path, level):
+    while level > 0:
+        path = os.path.dirname(path)
+        level -= 1
+
+    return path
+
+bootstrap_py = os.path.join(ancestor(__file__, 4), 'bootstrap', 'bootstrap.py')
 
 def bootstrapSetup(test):
     buildout_txt_setup(test)
@@ -3449,6 +3454,15 @@ normalize_S = (
     '#!/usr/local/bin/python2.7',
     )
 
+def run_buildout(command):
+    os.environ['HOME'] = os.getcwd() # Make sure we don't get .buildout
+    args = command.strip().split()
+    import pkg_resources
+    buildout = pkg_resources.load_entry_point(
+        'zc.buildout', 'console_scripts', args[0])
+    sys.stdout = sys.stderr = open('out', 'w')
+    buildout(args[1:])
+
 def test_suite():
     test_suite = [
         manuel.testing.TestSuite(
@@ -3710,6 +3724,56 @@ def test_suite():
         unittest.makeSuite(UnitTests),
     ]
 
+    docdir = os.path.join(ancestor(__file__, 4), 'doc')
+    if os.path.exists(docdir) and not sys.platform.startswith('win'):
+        # Note that the purpose of the documentation tests are mainly
+        # to test the documentation, not to test buildout.
+
+        def docSetUp(test):
+            extra_options = (
+                " use-dependency-links=false"
+                # Leaving this here so we can uncomment to see what's going on.
+                #" log-format=%(asctime)s____%(levelname)s_%(message)s -vvv"
+                " index=" + os.path.join(ancestor(__file__, 4), 'doc')
+                )
+            def run_buildout_in_process(command='buildout'):
+                process = Process(
+                    target=run_buildout,
+                    args=(command + extra_options, ),
+                    )
+                process.daemon = True
+                process.start()
+                process.join(99)
+                if process.is_alive() or process.exitcode:
+                    print(read())
+
+            def read(path='out'):
+                with open(path) as f:
+                    return f.read()
+
+            def write(text, path):
+                with open(path, 'w') as f:
+                    f.write(text)
+
+            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),
+                read=read,
+                write=write,
+                )
+            setupstack.setUpDirectory(test)
+
+        test_suite.append(
+            manuel.testing.TestSuite(
+                manuel.doctest.Manuel() + manuel.capture.Manuel(),
+                os.path.join(docdir, 'getting-started.rst'),
+                setUp=docSetUp, tearDown=setupstack.tearDown
+                ))
+
+
     # adding bootstrap.txt doctest to the suite
     # only if bootstrap.py is present
     if os.path.exists(bootstrap_py):