[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