enable doctest plugin by default, add a --doctest-glob option and some documentation, regen plugin docs.

--HG--
branch : trunk

CHANGELOG

@@ -44,6 +44,9 @@ Changes between 1.X and 1.1.1
   on by default (requires the 'figleaf' package though).  Change
   long command line options to be a bit shorter (see py.test -h).
 
+- change: pytest doctest plugin is now enabled by default and has a
+  new option --doctest-glob to set a pattern for file matches. 
+
 - robustify capturing to survive if custom pytest_runtest_setup 
   code failed and prevented the capturing setup code from running. 
 

doc/test/plugin/doctest.txt

@@ -10,20 +10,31 @@ collect and execute doctests from modules and test files.
 Usage
 -------------
 
-By default all files matching the ``test_*.txt`` pattern will 
+By default all files matching the ``test*.txt`` pattern will 
-be run with the ``doctest`` module.  If you issue::
+be run through the python standard ``doctest`` module.  Issue::
+
+    py.test --doctest-glob='*.rst'
+
+to change the pattern.  Additionally you can trigger running of
+tests in all python modules (including regular python test modules)::
 
     py.test --doctest-modules
 
-all python files in your projects will be doctest-run 
+You can also make these changes permanent in your project by 
-as well.
+putting them into a conftest.py file like this::
+
+    # content of conftest.py 
+    option_doctestmodules = True
+    option_doctestglob = "*.rst"
 
 command line options
 --------------------
 
 
 ``--doctest-modules``
-    search all python files for doctests
+    run doctests in all .py modules
+``--doctest-glob=pat``
+    doctests file matching pattern, default: test*.txt
 
 Start improving this plugin in 30 seconds
 =========================================

doc/test/plugin/figleaf.txt

@@ -13,12 +13,12 @@ command line options
 --------------------
 
 
-``-F``
+``--figleaf``
     trace python coverage with figleaf and write HTML for files below the current working dir
-``--figleaf-data=FIGLEAFDATA``
+``--fig-data=dir``
-    path to coverage tracing file.
+    set tracing file, default: ".figleaf".
-``--figleaf-html=FIGLEAFHTML``
+``--fig-html=dir``
-    path to the coverage html dir.
+    set html reporting dir, default "html").
 
 Start improving this plugin in 30 seconds
 =========================================

doc/test/plugin/hookspec.txt

@@ -32,6 +32,7 @@ hook specification sourcecode
     
     def pytest_collect_directory(path, parent):
         """ return Collection node or None for the given path. """
+    pytest_collect_directory.firstresult = True
     
     def pytest_collect_file(path, parent):
         """ return Collection node or None for the given path. """

py/impl/test/pluginmanager.py

@@ -9,7 +9,7 @@ from py.impl.test.outcome import Skipped
 default_plugins = (
     "default runner capture terminal mark skipping tmpdir monkeypatch "
     "recwarn pdb pastebin unittest helpconfig nose assertion genscript "
-    "logxml figleaf").split()
+    "logxml figleaf doctest").split()
 
 def check_old_use(mod, modname):
     clsname = modname[len('pytest_'):].capitalize() + "Plugin" 

py/plugin/pytest_doctest.py

@@ -4,13 +4,22 @@ collect and execute doctests from modules and test files.
 Usage
 -------------
 
-By default all files matching the ``test_*.txt`` pattern will 
+By default all files matching the ``test*.txt`` pattern will 
-be run with the ``doctest`` module.  If you issue::
+be run through the python standard ``doctest`` module.  Issue::
+
+    py.test --doctest-glob='*.rst'
+
+to change the pattern.  Additionally you can trigger running of
+tests in all python modules (including regular python test modules)::
 
     py.test --doctest-modules
 
-all python files in your projects will be doctest-run 
+You can also make these changes permanent in your project by 
-as well. 
+putting them into a conftest.py file like this::
+
+    # content of conftest.py 
+    option_doctestmodules = True
+    option_doctestglob = "*.rst"
 """
 
 import py
@@ -21,14 +30,19 @@ def pytest_addoption(parser):
     group = parser.getgroup("general")
     group.addoption("--doctest-modules", 
         action="store_true", default=False, 
-        help="search all python files for doctests", 
+        help="run doctests in all .py modules",
         dest="doctestmodules")
+    group.addoption("--doctest-glob",
+        action="store", default="test*.txt", metavar="pat",
+        help="doctests file matching pattern, default: test*.txt",
+        dest="doctestglob")
 
 def pytest_collect_file(path, parent):
+    config = parent.config
     if path.ext == ".py":
-        if parent.config.getvalue("doctestmodules"):
+        if config.getvalue("doctestmodules"):
             return DoctestModule(path, parent)
-    if path.check(fnmatch="test_*.txt"):
+    elif path.check(fnmatch=config.getvalue("doctestglob")):
         return DoctestTextfile(path, parent)
 
 class ReprFailDoctest(TerminalRepr):

py/plugin/pytest_figleaf.py

@@ -17,7 +17,7 @@ def pytest_addoption(parser):
             help='set tracing file, default: ".figleaf".')
     group.addoption('--fig-html', action='store', default='html',
             dest='figleafhtml', metavar="dir",
-            help='set html reporting dir, default "html").')
+            help='set html reporting dir, default "html".')
 
 def pytest_configure(config):
     if config.getvalue("figleaf"):

testing/plugin/test_pytest_doctest.py

@@ -14,14 +14,14 @@ class TestDoctests:
         """)
         for x in (testdir.tmpdir, checkfile): 
             #print "checking that %s returns custom items" % (x,) 
-            items, reprec = testdir.inline_genitems(x, '-p', 'doctest')
+            items, reprec = testdir.inline_genitems(x)
             assert len(items) == 1
             assert isinstance(items[0], DoctestTextfile)
 
     def test_collect_module(self, testdir):
         path = testdir.makepyfile(whatever="#")
         for p in (path, testdir.tmpdir): 
-            items, reprec = testdir.inline_genitems(p, '-p', 'doctest', 
+            items, reprec = testdir.inline_genitems(p, 
                 '--doctest-modules')
             assert len(items) == 1
             assert isinstance(items[0], DoctestModule)
@@ -32,7 +32,16 @@ class TestDoctests:
             >>> x == 1
             False
         """)
-        reprec = testdir.inline_run(p, '-p', 'doctest')
+        reprec = testdir.inline_run(p, )
+        reprec.assertoutcome(failed=1)
+
+    def test_new_pattern(self, testdir):
+        p = testdir.maketxtfile(xdoc ="""
+            >>> x = 1
+            >>> x == 1
+            False
+        """)
+        reprec = testdir.inline_run(p, "--doctest-glob=x*.txt")
         reprec.assertoutcome(failed=1)
 
     def test_doctest_unexpected_exception(self, testdir):
@@ -44,7 +53,7 @@ class TestDoctests:
             >>> x
             2
         """)
-        reprec = testdir.inline_run(p, '-p', 'doctest')
+        reprec = testdir.inline_run(p)
         call = reprec.getcall("pytest_runtest_logreport")
         assert call.report.failed
         assert call.report.longrepr 
@@ -63,7 +72,7 @@ class TestDoctests:
 
             '''
         """)
-        reprec = testdir.inline_run(p, '-p', 'doctest', "--doctest-modules")
+        reprec = testdir.inline_run(p, "--doctest-modules")
         reprec.assertoutcome(failed=1) 
 
     def test_doctestmodule_external(self, testdir):
@@ -76,7 +85,7 @@ class TestDoctests:
                     2
                 '''
         """)
-        result = testdir.runpytest(p, '-p', 'doctest', "--doctest-modules")
+        result = testdir.runpytest(p, "--doctest-modules")
         result.stdout.fnmatch_lines([
             '004 *>>> i = 0',
             '005 *>>> i + 1',
@@ -94,7 +103,7 @@ class TestDoctests:
             >>> i + 1
             2
         """)
-        result = testdir.runpytest(p, '-p', 'doctest')
+        result = testdir.runpytest(p)
         result.stdout.fnmatch_lines([
             '001 >>> i = 0',
             '002 >>> i + 1',