[Checkins] SVN: manuel/trunk/src/ - documentation enhancements
Benji York
benji at zope.com
Sun Jun 21 14:52:54 EDT 2009
Log message for revision 101201:
- documentation enhancements
- removed Manuel instances' "extend" method, now implements "__add__" instead
Changed:
U manuel/trunk/src/getting-started.txt
U manuel/trunk/src/intro.txt
U manuel/trunk/src/manuel/README.txt
U manuel/trunk/src/manuel/__init__.py
U manuel/trunk/src/manuel/codeblock.txt
U manuel/trunk/src/manuel/doctest.txt
U manuel/trunk/src/manuel/footnote.txt
U manuel/trunk/src/manuel/ignore.py
U manuel/trunk/src/manuel/ignore.txt
U manuel/trunk/src/manuel/isolation.txt
U manuel/trunk/src/manuel/table-example.txt
U manuel/trunk/src/manuel/tests.py
-=-
Modified: manuel/trunk/src/getting-started.txt
===================================================================
--- manuel/trunk/src/getting-started.txt 2009-06-21 17:07:40 UTC (rev 101200)
+++ manuel/trunk/src/getting-started.txt 2009-06-21 18:52:54 UTC (rev 101201)
@@ -1,11 +1,36 @@
+.. _getting-started:
+
Getting Started
===============
-The simplest way to get started with Manuel is to create a script to run your
-tests, like so:
+The plug-ins used for a test are composed together using the "+" operator.
+Let's say you wanted a test that used doctest syntax as well as footnotes. You
+would create a Manuel instance to use like this:
.. code-block:: python
+ import manuel.doctest
+ import manuel.footnote
+
+ m = manuel.doctest.Manuel() + manuel.footnote.Manuel()
+
+You would then pass the Manuel instance to a :class:`manuel.testing.TestSuite`,
+including the names of documents you want to process:
+
+.. ignore-next-block
+.. code-block:: python
+
+ manuel.testing.TestSuite(m, 'test-one.txt', 'test-two.txt')
+
+
+Using unittest
+--------------
+
+The simplest way to get started with Manuel is to use :mod:`unittest` to run
+your tests:
+
+.. code-block:: python
+
import manuel.codeblock
import manuel.doctest
import manuel.testing
@@ -13,7 +38,7 @@
def test_suite():
m = manuel.doctest.Manuel()
- m.extend(manuel.codeblock.Manuel())
+ m += manuel.codeblock.Manuel()
return manuel.testing.TestSuite(m, 'test-one.txt', 'test-two.txt')
if __name__ == '__main__':
@@ -23,10 +48,14 @@
Using zope.testing
------------------
-If you want to use zope.testing's test runner (usable stand-alone, it isn't
-dependent on the Zope application server), you can add Manuel tests to the
-TestSuite objects you're already creating.
+If you want to use a more featurfull test runner you can use zope.testing's
+test runner (usable stand-alone -- it isn't dependent on the Zope application
+server). Create a file named :file:`tests.py` with a :func:`test_setup`
+function that returns a test suite.
+The suite can be either a :class:`manuel.testing.TestSuite` object or a
+:class:`unittest.TestSuite` as demonstrated below.
+
.. code-block:: python
import manuel.codeblock
@@ -40,7 +69,7 @@
# now you can add the Manuel tests
m = manuel.doctest.Manuel()
- m.extend(manuel.codeblock.Manuel())
+ m += manuel.codeblock.Manuel()
suite.addTest(manuel.testing.TestSuite(m,
'test-one.txt', 'test-two.txt'))
@@ -50,7 +79,7 @@
Others
------
-If you know how to make Manuel work with other test runners, please `send me an
-email`_.
+If you figure out how to make Manuel work with other test runners (nose,
+py.test, etc.), please `send me an email`_ and I'll expand this section.
.. _send me an email: benji+manuel at benjiyork.com
Modified: manuel/trunk/src/intro.txt
===================================================================
--- manuel/trunk/src/intro.txt 2009-06-21 17:07:40 UTC (rev 101200)
+++ manuel/trunk/src/intro.txt 2009-06-21 18:52:54 UTC (rev 101201)
@@ -3,8 +3,8 @@
Manuel lets you mix and match traditional doctests with custom test syntax.
-Several plug-ins that provide new syntaxes are included. You can also make
-your own.
+Manuel include plug-ins that provide new test syntax, and you create make your
+own.
For example, if you've ever wanted to include a large chunk of Python in a
doctest but were irritated by all the ">>>" and "..." prompts required, you'd
@@ -22,12 +22,13 @@
Incidentally, the implementation of :mod:`manuel.codeblock` is only 22 lines of
code.
+The plug-ins included in Manuel make good examples while being quite useful in
+their own right. All the included plug-ins are listed in the next section.
+
For a large example of creating test syntax, take a look at the
:ref:`fit-table-example` or for all the details, :ref:`theory-of-operation`.
-Also, the plug-ins included in Manuel make good examples while being quite
-useful in their own right. All the included plug-ins are listed in the next
-section.
+Once you've decided to use Manuel, see the :ref:`getting-started` section.
Included Functionality
Modified: manuel/trunk/src/manuel/README.txt
===================================================================
--- manuel/trunk/src/manuel/README.txt 2009-06-21 17:07:40 UTC (rev 101200)
+++ manuel/trunk/src/manuel/README.txt 2009-06-21 18:52:54 UTC (rev 101201)
@@ -319,7 +319,7 @@
Since we already have a Manuel instance configured for our "sorted numbers"
tests, we can extend the built-in doctest configuration with it.
- >>> m.extend(sorted_numbers_manuel)
+ >>> m += sorted_numbers_manuel
Now we can process our source that combines both types of tests and see what
we get.
Modified: manuel/trunk/src/manuel/__init__.py
===================================================================
--- manuel/trunk/src/manuel/__init__.py 2009-06-21 17:07:40 UTC (rev 101200)
+++ manuel/trunk/src/manuel/__init__.py 2009-06-21 18:52:54 UTC (rev 101201)
@@ -315,7 +315,14 @@
def add_formatter(self, formatter):
self.formatters.append(formatter)
- def extend(self, other):
+ def __extend(self, other):
self.parsers.extend(other.parsers)
self.evaluaters.extend(other.evaluaters)
self.formatters.extend(other.formatters)
+
+ def __add__(self, other):
+ m = Manuel()
+ m.__extend(self)
+ m.__extend(other)
+ return m
+
Modified: manuel/trunk/src/manuel/codeblock.txt
===================================================================
--- manuel/trunk/src/manuel/codeblock.txt 2009-06-21 17:07:40 UTC (rev 101200)
+++ manuel/trunk/src/manuel/codeblock.txt 2009-06-21 18:52:54 UTC (rev 101201)
@@ -18,9 +18,10 @@
The :mod:`manuel.codeblock` module provides the ability to execute the contents
of Python code-blocks.
- >>> import manuel.codeblock
- >>> m = manuel.codeblock.Manuel()
+.. code-block:: python
+ import manuel.codeblock
+
.. Let's create a reST document with a code block.
>>> document = manuel.Document("""
@@ -41,27 +42,30 @@
doctest handler.
>>> import manuel.doctest
- >>> m.extend(manuel.doctest.Manuel())
+ >>> m = manuel.codeblock.Manuel()
+ >>> m += manuel.doctest.Manuel()
>>> document.process_with(m, globs={})
-.. Both code blocks were found (for a total of five regions -- text, block,
+ Both code blocks were found (for a total of five regions -- text, block,
text, block, and text):
>>> len(list(document))
5
-.. We can see that none of the tests in the document failed:
+ We can see that none of the tests in the document failed:
>>> print document.formatted(),
If the code-block generates some sort of error...
- >>> document = manuel.Document("""\
- ... .. code-block:: python
- ...
- ... print does_not_exist
- ... """)
+.. code-block:: python
+ document = manuel.Document("""\
+ .. code-block:: python
+
+ print does_not_exist
+ """)
+
.. the document above was specially formulated to have nothing before or after
the code-block
@@ -72,6 +76,7 @@
...that error will be reported:
+ >>> m = manuel.codeblock.Manuel()
>>> document.process_with(m, globs={})
Traceback (most recent call last):
...
Modified: manuel/trunk/src/manuel/doctest.txt
===================================================================
--- manuel/trunk/src/manuel/doctest.txt 2009-06-21 17:07:40 UTC (rev 101200)
+++ manuel/trunk/src/manuel/doctest.txt 2009-06-21 18:52:54 UTC (rev 101201)
@@ -25,7 +25,7 @@
import manuel.codeblock
m = manuel.doctest.Manuel()
- m.extend(manuel.codeblock.Manuel())
+ m += manuel.codeblock.Manuel()
suite = manuel.testing.TestSuite(m, 'my-doctest-with-code-blocks.txt')
The :class:`manuel.doctest.Manuel` constructor also takes :data:`optionflags`
Modified: manuel/trunk/src/manuel/footnote.txt
===================================================================
--- manuel/trunk/src/manuel/footnote.txt 2009-06-21 17:07:40 UTC (rev 101200)
+++ manuel/trunk/src/manuel/footnote.txt 2009-06-21 18:52:54 UTC (rev 101201)
@@ -13,7 +13,7 @@
We'll try the footnotes out by combining them with doctests.
>>> import manuel.doctest
- >>> m.extend(manuel.doctest.Manuel())
+ >>> m += manuel.doctest.Manuel()
>>> import manuel
>>> document = manuel.Document("""\
... Here we reference a footnote. [1]_
Modified: manuel/trunk/src/manuel/ignore.py
===================================================================
--- manuel/trunk/src/manuel/ignore.py 2009-06-21 17:07:40 UTC (rev 101200)
+++ manuel/trunk/src/manuel/ignore.py 2009-06-21 18:52:54 UTC (rev 101201)
@@ -12,6 +12,7 @@
document.replace_region(region, None)
document.remove_region(region)
+
class Manuel(manuel.Manuel):
def __init__(self):
manuel.Manuel.__init__(self, [find_ignores])
Modified: manuel/trunk/src/manuel/ignore.txt
===================================================================
--- manuel/trunk/src/manuel/ignore.txt 2009-06-21 17:07:40 UTC (rev 101200)
+++ manuel/trunk/src/manuel/ignore.txt 2009-06-21 18:52:54 UTC (rev 101201)
@@ -42,8 +42,8 @@
import manuel.ignore
import manuel.doctest
m = manuel.ignore.Manuel()
- m.extend(manuel.codeblock.Manuel())
- m.extend(manuel.doctest.Manuel())
+ m += manuel.codeblock.Manuel()
+ m += manuel.doctest.Manuel()
If we add an ignore marker to the block we don't want processed...
Modified: manuel/trunk/src/manuel/isolation.txt
===================================================================
--- manuel/trunk/src/manuel/isolation.txt 2009-06-21 17:07:40 UTC (rev 101200)
+++ manuel/trunk/src/manuel/isolation.txt 2009-06-21 18:52:54 UTC (rev 101201)
@@ -39,7 +39,7 @@
handler.
>>> import manuel.doctest
- >>> m.extend(manuel.doctest.Manuel())
+ >>> m += manuel.doctest.Manuel()
We can see that after the globals have been reset, the "print x" line raises an
error.
Modified: manuel/trunk/src/manuel/table-example.txt
===================================================================
--- manuel/trunk/src/manuel/table-example.txt 2009-06-21 17:07:40 UTC (rev 101200)
+++ manuel/trunk/src/manuel/table-example.txt 2009-06-21 18:52:54 UTC (rev 101201)
@@ -300,26 +300,10 @@
>>> document.process_with(m, globs={})
>>> print document.formatted()
+If we wanted to use instances of our Manuel object in a test, we would follow
+the directions in :ref:`getting-started`, importing Manuel from the module
+where we placed the code, just like any other Manuel plug-in.
-Unittest Integration
---------------------
-
-If we wanted to use our new table tests in conjunction with unittest, we could
-put the code above in tableexample.py. Then to use the new syntax in a test
-file named "my-table-tests.txt" we can create a file named tests.py and build a
-TestSuite like so:
-
-.. ignore-next-block
-.. code-block:: python
-
- import unittest
- import manuel.testing
- import tableexample
-
- def test_suite():
- m = tableexample.Manuel()
- return manuel.testing.TestSuite(m, 'my-table-tests.txt')
-
.. this next bit is actually a reST comment, but it is run during tests anyway
(note the single colon instead of double colon)
@@ -328,7 +312,8 @@
import unittest
suite = manuel.testing.TestSuite(m, 'table-example.txt')
-If the tests are run (e.g., by a test runner), everything works.
+.. run this file through the Manuel instance constructed above to ensure it
+ actually works when given a real file to process
>>> suite.run(unittest.TestResult())
<unittest.TestResult run=1 errors=0 failures=0>
Modified: manuel/trunk/src/manuel/tests.py
===================================================================
--- manuel/trunk/src/manuel/tests.py 2009-06-21 17:07:40 UTC (rev 101200)
+++ manuel/trunk/src/manuel/tests.py 2009-06-21 18:52:54 UTC (rev 101201)
@@ -37,8 +37,8 @@
tests = map(get_abs_path, tests)
m = manuel.ignore.Manuel()
- m.extend(manuel.doctest.Manuel(optionflags=optionflags, checker=checker))
- m.extend(manuel.codeblock.Manuel())
+ m += manuel.doctest.Manuel(optionflags=optionflags, checker=checker)
+ m += manuel.codeblock.Manuel()
suite.addTest(manuel.testing.TestSuite(m, *tests))
return suite
More information about the Checkins
mailing list