[Epydoc-commits] SF.net SVN: epydoc: [1380] trunk/epydoc

[<dva...@us...>]

Revision: 1380
          http://svn.sourceforge.net/epydoc/?rev=1380&view=rev
Author:   dvarrazzo
Date:     2006-09-10 09:31:38 -0700 (Sun, 10 Sep 2006)

Log Message:
-----------
- defining_module is propagated to object which don't have other means
  to detect it, such as properties. So docformat can be correctly detected
  for such objects too.

- Added a test suite to verify docbuilder behavior.

Modified Paths:
--------------
    trunk/epydoc/doc/doctest/index.html
    trunk/epydoc/src/epydoc/docbuilder.py

Added Paths:
-----------
    trunk/epydoc/src/epydoc/test/docbuilder.doctest

Modified: trunk/epydoc/doc/doctest/index.html
===================================================================
--- trunk/epydoc/doc/doctest/index.html	2006-09-10 16:23:49 UTC (rev 1379)
+++ trunk/epydoc/doc/doctest/index.html	2006-09-10 16:31:38 UTC (rev 1380)
@@ -27,6 +27,9 @@
   <li> <a href="docparser.html">Source Code Parsing</a> --
        Extracting API information about Python objects by parsing
        their source code.</li>
+  <li> <a href="docbuilder.html">Documentation building</a> --
+       Merging different information sources into a single API
+       hypertext.
   <li> <a href="encoding.html">Unicode & Encodings</a> --
        Tests for the processing of Python files that use non-ascii
        encodings. </li>

Modified: trunk/epydoc/src/epydoc/docbuilder.py
===================================================================
--- trunk/epydoc/src/epydoc/docbuilder.py	2006-09-10 16:23:49 UTC (rev 1379)
+++ trunk/epydoc/src/epydoc/docbuilder.py	2006-09-10 16:31:38 UTC (rev 1380)
@@ -188,6 +188,12 @@
         if (isinstance(val_doc, NamespaceDoc) and
             val_doc.variables not in (None, UNKNOWN)):
             for var_doc in val_doc.variables.values():
+                # Now we have a chance to propagate the defining module
+                # to objects for which introspection is not possible,
+                # such as properties.
+                if (isinstance(var_doc.value, ValueDoc)
+                    and var_doc.value.defining_module is UNKNOWN):
+                    var_doc.value.defining_module = val_doc.defining_module
                 parse_docstring(var_doc, docindex)
     log.end_progress()
 

Added: trunk/epydoc/src/epydoc/test/docbuilder.doctest
===================================================================
--- trunk/epydoc/src/epydoc/test/docbuilder.doctest	                        (rev 0)
+++ trunk/epydoc/src/epydoc/test/docbuilder.doctest	2006-09-10 16:31:38 UTC (rev 1380)
@@ -0,0 +1,117 @@
+Regression Testing for epydoc.docbuilder
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Test Function
+=============
+
+This test function takes a string containing the contents of a module.
+It writes the string contents to a file, imports the file as a module,
+and uses build_doc to build documentation, and pretty prints the resulting
+ModuleDoc object.  The `attribs` argument specifies which attributes
+of the `APIDoc`s should be displayed.  The `build` argument gives the
+name of a variable in the module whose documentation should be built,
+instead of bilding docs for the whole module.
+
+    >>> import tempfile, re, os, os.path, textwrap, sys
+    >>> from epydoc.docbuilder import build_doc
+    >>> def runbuilder(s, attribs='', build=None, exclude=''):
+    ...     # Write it to a temp file.
+    ...     tmp_dir = tempfile.mkdtemp()
+    ...     out = open(os.path.join(tmp_dir, 'epydoc_test.py'), 'w')
+    ...     out.write(textwrap.dedent(s))
+    ...     out.close()
+    ...     # Build it.
+    ...     val_doc = build_doc(os.path.join(tmp_dir, 'epydoc_test.py'))
+    ...     if build: val_doc = val_doc.variables[build].value
+    ...     # Display it.
+    ...     s = val_doc.pp(include=attribs.split(),exclude=exclude.split())
+    ...     s = re.sub(r"(filename = ).*", r"\1...", s)
+    ...     s = re.sub(r"(<module 'epydoc_test' from ).*", r'\1...', s)
+    ...     s = re.sub(r"(<function \w+ at )0x\w+>", r"\1...>", s)
+    ...     s = re.sub(r"(<\w+ object at )0x\w+>", r"\1...>", s)
+    ...     print s
+    ...     # Clean up.
+    ...     os.unlink(os.path.join(tmp_dir, 'epydoc_test.py'))
+    ...     try: os.unlink(os.path.join(tmp_dir, 'epydoc_test.pyc'))
+    ...     except OSError: pass
+    ...     os.rmdir(tmp_dir)
+    ...     del sys.modules['epydoc_test']
+
+Docformat selection
+===================
+
+The docstrings format can be selected using the ``__docformat__`` module
+variable.
+
+    >>> runbuilder(s='''
+    ...     __docformat__ = 'restructuredtext'
+    ...
+    ...     class Foo:
+    ...         """Testing defining_module
+    ...
+    ...         :cvar `c`: class var in class docstring
+    ...         :type `c`: str
+    ...         """
+    ...         c = 'abc'
+    ...
+    ...         def __init__(self):
+    ...             #: A funny number
+    ...             #:
+    ...             #: :type: float
+    ...             self.x = 108.0
+    ...
+    ...         y = property(
+    ...             fget=lambda self: 42,
+    ...             doc="""A property has no defining module
+    ...
+    ...             :type: int
+    ...             """)
+    ...
+    ...         def f(self):
+    ...             """A function has a defining module
+    ...
+    ...             :rtype: int
+    ...             """
+    ...             return 42
+    ...     ''',
+    ...     build='Foo',
+    ...     attribs="variables name value type_descr return_type descr")
+    ClassDoc for epydoc_test.Foo [0]
+     +- descr = u'Testing defining_module'
+     +- variables
+        +- __init__ => VariableDoc for epydoc_test.Foo.__init__ [1]
+        |  +- descr = None
+        |  +- name = '__init__'
+        |  +- type_descr = None
+        |  +- value
+        |     +- RoutineDoc for epydoc_test.Foo.__init__ [2]
+        |        +- descr = None
+        |        +- return_type = None
+        +- c => VariableDoc for epydoc_test.Foo.c [3]
+        |  +- descr = u'class var in class docstring'
+        |  +- name = 'c'
+        |  +- type_descr = u'str'
+        |  +- value
+        |     +- GenericValueDoc [4]
+        |        +- descr = None
+        +- f => VariableDoc for epydoc_test.Foo.f [5]
+        |  +- descr = None
+        |  +- name = 'f'
+        |  +- type_descr = None
+        |  +- value
+        |     +- RoutineDoc for epydoc_test.Foo.f [6]
+        |        +- descr = u'A function has a defining module'
+        |        +- return_type = u'int'
+        +- x => VariableDoc for epydoc_test.Foo.x [7]
+        |  +- descr = u'A funny number'
+        |  +- name = u'x'
+        |  +- type_descr = u'float'
+        |  +- value = <UNKNOWN>
+        +- y => VariableDoc for epydoc_test.Foo.y [8]
+           +- descr = None
+           +- name = 'y'
+           +- type_descr = None
+           +- value
+              +- PropertyDoc for epydoc_test.Foo.y [9]
+                 +- descr = u'A property has no defining module'
+                 +- type_descr = u'int'


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.