[Checkins] SVN: manuel/trunk/ - more work on documentation
Benji York
benji at zope.com
Mon Jun 15 23:56:10 EDT 2009
Log message for revision 101028:
- more work on documentation
- first stab at making tests run with nose -- doesn't work yet
Changed:
U manuel/trunk/buildout.cfg
U manuel/trunk/src/index.txt
U manuel/trunk/src/intro.txt
U manuel/trunk/src/manuel/README.txt
D manuel/trunk/src/manuel/code-block.txt
A manuel/trunk/src/manuel/codeblock.txt
U manuel/trunk/src/manuel/footnote.txt
U manuel/trunk/src/manuel/isolation.txt
U manuel/trunk/src/manuel/table-example.txt
U manuel/trunk/src/manuel/testing.py
U manuel/trunk/src/manuel/tests.py
-=-
Modified: manuel/trunk/buildout.cfg
===================================================================
--- manuel/trunk/buildout.cfg 2009-06-16 00:06:35 UTC (rev 101027)
+++ manuel/trunk/buildout.cfg 2009-06-16 03:56:08 UTC (rev 101028)
@@ -1,6 +1,6 @@
[buildout]
develop = .
-parts = test interpreter sphinx-docs-html build-docs
+parts = test interpreter sphinx-docs-html build-docs nosetests
allow-picked-versions = false
use-dependency-links = false
versions = versions
@@ -11,6 +11,12 @@
defaults = '--tests-pattern tests --exit-with-status -1 --auto-color'.split()
working-directory = .
+# XXX doesn't work yet, either fix or rip out
+[nosetests]
+recipe = pbp.recipe.noserunner
+eggs = manuel
+working-directory = ${buildout:directory}
+
[interpreter]
recipe = zc.recipe.egg
eggs = manuel
@@ -39,14 +45,16 @@
cmds = ${buildout:directory}/bin/docs
[versions]
+Jinja2 = 2.1.1
+PILwoTk = 1.1.6.3
+Pygments = 1.0
+Sphinx = 0.6.1
+docutils = 0.5
iw.recipe.cmd = 0.3
-docutils = 0.5
+nose = 0.11.1
+pbp.recipe.noserunner = 0.2.6
setuptools = 0.6c9
-PILwoTk = 1.1.6.3
zc.buildout = 1.2.1
-Sphinx = 0.6.1
-Jinja2 = 2.1.1
-Pygments = 1.0
zc.recipe.egg = 1.2.2
zc.recipe.testrunner = 1.2.0
zope.interface = 3.5.1
Modified: manuel/trunk/src/index.txt
===================================================================
--- manuel/trunk/src/index.txt 2009-06-16 00:06:35 UTC (rev 101027)
+++ manuel/trunk/src/index.txt 2009-06-16 03:56:08 UTC (rev 101028)
@@ -9,7 +9,7 @@
intro.txt
manuel/README.txt
manuel/table-example.txt
- manuel/code-block.txt
+ manuel/codeblock.txt
manuel/footnote.txt
manuel/isolation.txt
manuel/bugs.txt
Modified: manuel/trunk/src/intro.txt
===================================================================
--- manuel/trunk/src/intro.txt 2009-06-16 00:06:35 UTC (rev 101027)
+++ manuel/trunk/src/intro.txt 2009-06-16 03:56:08 UTC (rev 101028)
@@ -2,12 +2,12 @@
============
Manuel lets you mix and match traditional doctests with new test syntax that
-you create or is included in Manuel.
+either you create or comes bundled with Manuel.
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
-like the "manuel.codeblock" module. It lets you include code using Sphinx-style
-".. code-block:: python" directives, like so:
+like the "manuel.codeblock" module. It lets you execute code using
+Sphinx-style ".. code-block:: python" directives, like so:
.. code-block:: python
@@ -18,8 +18,8 @@
Incidentally, the implementation of manuel.codeblock is only 24 lines of code.
-For an example of creating your own test syntax, take a look at
-table-example.txt or for full details, README.txt.
+For an example of creating your own test syntax, take a look at the
+:ref:`fit-table-example` or for all the details, :ref:`theory-of-operation`.
Included Functionality
@@ -27,12 +27,18 @@
Manuel includes several extentions to doctest out of the box.
-manuel.codeblock
+:ref:`manuel.codeblock <code-blocks>`
executes code in ".. code-block:: python" blocks
-manuel.footnote
+:ref:`manuel.footnote <footnotes>`
executes code in reST-style footnodes each time they're referenced (good
for getting incedental code out of the main flow of a document)
-manuel.isolation
+:ref:`manuel.isolation <isolation>`
makes it easier to have test isolation in doctests
+
+
+Getting Started
+===============
+
+If you already have XXX
Modified: manuel/trunk/src/manuel/README.txt
===================================================================
--- manuel/trunk/src/manuel/README.txt 2009-06-16 00:06:35 UTC (rev 101027)
+++ manuel/trunk/src/manuel/README.txt 2009-06-16 03:56:08 UTC (rev 101028)
@@ -1,3 +1,5 @@
+.. _theory-of-operation:
+
Theory of Operation
===================
Deleted: manuel/trunk/src/manuel/code-block.txt
===================================================================
--- manuel/trunk/src/manuel/code-block.txt 2009-06-16 00:06:35 UTC (rev 101027)
+++ manuel/trunk/src/manuel/code-block.txt 2009-06-16 03:56:08 UTC (rev 101028)
@@ -1,44 +0,0 @@
-Code Blocks
-===========
-
-`Sphinx <http://sphinx.pocoo.org/>`_ and other docutils `extensions
-<http://docutils.sourceforge.net/sandbox/code-block-directive/docs/syntax-highlight.html>`_
-provide a `"code-block" directive <http://sphinx.pocoo.org/markup/code.html>`_
-allows inlined snippets of code in `reST
-<http://docutils.sourceforge.net/rst.html>`_ documents.
-
-For example a block of Python would be prefixed with ".. code-block:: python"::
-
- .. code-block:: python
-
- print 'hello'
-
-The manuel.codeblock module provides the ability to execute the contents of
-Python code-blocks.
-
- >>> import manuel.codeblock
- >>> m = manuel.codeblock.Manuel()
-
-Let's create a reST document with a code block.
-
- >>> document = manuel.Document("""
- ... Here is a code-block:
- ...
- ... .. code-block:: python
- ...
- ... x = 'hello'
- ...
- ... A little prose to separate the examples.
- ...
- ... >>> print x
- ... hello
- ...
- ... """)
-
-Since the above document mixes code-blocks and doctests, we'll mix in the
-doctest handler.
-
- >>> import manuel.doctest
- >>> m.extend(manuel.doctest.Manuel())
- >>> document.process_with(m, globs={})
- >>> print document.formatted()
Copied: manuel/trunk/src/manuel/codeblock.txt (from rev 101027, manuel/trunk/src/manuel/code-block.txt)
===================================================================
--- manuel/trunk/src/manuel/codeblock.txt (rev 0)
+++ manuel/trunk/src/manuel/codeblock.txt 2009-06-16 03:56:08 UTC (rev 101028)
@@ -0,0 +1,46 @@
+.. _code-blocks:
+
+Code Blocks
+===========
+
+`Sphinx <http://sphinx.pocoo.org/>`_ and other docutils `extensions
+<http://docutils.sourceforge.net/sandbox/code-block-directive/docs/syntax-highlight.html>`_
+provide a `"code-block" directive <http://sphinx.pocoo.org/markup/code.html>`_
+allows inlined snippets of code in `reST
+<http://docutils.sourceforge.net/rst.html>`_ documents.
+
+For example a block of Python would be prefixed with ".. code-block:: python"::
+
+ .. code-block:: python
+
+ print 'hello'
+
+The manuel.codeblock module provides the ability to execute the contents of
+Python code-blocks.
+
+ >>> import manuel.codeblock
+ >>> m = manuel.codeblock.Manuel()
+
+Let's create a reST document with a code block.
+
+ >>> document = manuel.Document("""
+ ... Here is a code-block:
+ ...
+ ... .. code-block:: python
+ ...
+ ... x = 'hello'
+ ...
+ ... A little prose to separate the examples.
+ ...
+ ... >>> print x
+ ... hello
+ ...
+ ... """)
+
+Since the above document mixes code-blocks and doctests, we'll mix in the
+doctest handler.
+
+ >>> import manuel.doctest
+ >>> m.extend(manuel.doctest.Manuel())
+ >>> document.process_with(m, globs={})
+ >>> print document.formatted(),
Property changes on: manuel/trunk/src/manuel/codeblock.txt
___________________________________________________________________
Added: svn:mergeinfo
+
Added: svn:eol-style
+ native
Modified: manuel/trunk/src/manuel/footnote.txt
===================================================================
--- manuel/trunk/src/manuel/footnote.txt 2009-06-16 00:06:35 UTC (rev 101027)
+++ manuel/trunk/src/manuel/footnote.txt 2009-06-16 03:56:08 UTC (rev 101028)
@@ -1,3 +1,5 @@
+.. _footnotes:
+
=========
Footnotes
=========
Modified: manuel/trunk/src/manuel/isolation.txt
===================================================================
--- manuel/trunk/src/manuel/isolation.txt 2009-06-16 00:06:35 UTC (rev 101027)
+++ manuel/trunk/src/manuel/isolation.txt 2009-06-16 03:56:08 UTC (rev 101028)
@@ -1,3 +1,5 @@
+.. _isolation:
+
Test Isolation
==============
Modified: manuel/trunk/src/manuel/table-example.txt
===================================================================
--- manuel/trunk/src/manuel/table-example.txt 2009-06-16 00:06:35 UTC (rev 101027)
+++ manuel/trunk/src/manuel/table-example.txt 2009-06-16 03:56:08 UTC (rev 101028)
@@ -1,3 +1,5 @@
+.. _fit-table-example:
+
FIT Table Example
=================
Modified: manuel/trunk/src/manuel/testing.py
===================================================================
--- manuel/trunk/src/manuel/testing.py 2009-06-16 00:06:35 UTC (rev 101027)
+++ manuel/trunk/src/manuel/testing.py 2009-06-16 03:56:08 UTC (rev 101028)
@@ -1,11 +1,16 @@
from zope.testing import doctest
import manuel
+import os.path
import unittest
__all__ = ['TestSuite']
class TestCase(unittest.TestCase):
+
+ __test__ = False # tell nose not to treat this as a test case
+
+ # XXX this is broken, see the unittest.TestCase docstring
def __init__(self, m, document, setUp=None, tearDown=None, globs=None):
unittest.TestCase.__init__(self)
self.manuel = m
@@ -92,8 +97,13 @@
break
for path in paths:
- abs_path = doctest._module_relative_path(calling_module, path)
+ if os.path.isabs(path):
+ abs_path = path
+ else:
+ abs_path = doctest._module_relative_path(calling_module, path)
document = manuel.Document(open(abs_path).read(), location=abs_path)
suite.addTest(TestCase(m, document, **kws))
return suite
+
+TestSuite.__test__ = False # tell nose not to treat this as a test case
Modified: manuel/trunk/src/manuel/tests.py
===================================================================
--- manuel/trunk/src/manuel/tests.py 2009-06-16 00:06:35 UTC (rev 101027)
+++ manuel/trunk/src/manuel/tests.py 2009-06-16 03:56:08 UTC (rev 101028)
@@ -3,12 +3,21 @@
import manuel.codeblock
import manuel.doctest
import manuel.testing
+import os.path
import re
import unittest
#doctest = manuel.absolute_import('doctest')
from zope.testing import doctest
+
+def get_abs_path(p):
+ def fake():
+ pass
+ here = os.path.dirname(fake.func_code.co_filename)
+ return os.path.join(os.getcwd(), here, p)
+
+
def test_suite():
optionflags = doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS
checker = renormalizing.RENormalizing([
@@ -16,9 +25,11 @@
])
suite = unittest.TestSuite()
- tests = ['README.txt', 'footnote.txt', 'bugs.txt', 'code-block.txt',
+ tests = ['README.txt', 'footnote.txt', 'bugs.txt', 'codeblock.txt',
'isolation.txt', 'table-example.txt']
+ tests = map(get_abs_path, tests)
+
# run the tests with Manuel's doctest support
m = manuel.doctest.Manuel(optionflags=optionflags, checker=checker)
# add in the codeblock extension
@@ -27,3 +38,8 @@
suite.addTest(manuel.testing.TestSuite(m, *tests))
return suite
+
+test_suite.__test__ = False # tell nose not to treat this as a test case
+
+if __name__ == '__main__':
+ unittest.TextTestRunner().run(test_suite())
More information about the Checkins
mailing list