[Epydoc-commits] SF.net SVN: epydoc: [1389] branches/exp-args_in_class
Brought to you by:
edloper
Menu
▾
▴
[Epydoc-commits] SF.net SVN: epydoc: [1389] branches/exp-args_in_class
|
From: <dva...@us...> - 2006-09-14 21:37:55
|
Revision: 1389
http://svn.sourceforge.net/epydoc/?rev=1389&view=rev
Author: dvarrazzo
Date: 2006-09-14 14:37:38 -0700 (Thu, 14 Sep 2006)
Log Message:
-----------
Merged revisions 1376-1388 via svnmerge from
https://svn.sourceforge.net/svnroot/epydoc/trunk
........
r1377 | edloper | 2006-09-10 16:29:31 +0200 (Sun, 10 Sep 2006) | 4 lines
- Fixed bug where base tree generation would fail if the context
was UNKNOWN (e.g., if we can't determine what the containing
module is.)
........
r1378 | dvarrazzo | 2006-09-10 17:16:41 +0200 (Sun, 10 Sep 2006) | 2 lines
Fixed typo.
........
r1379 | dvarrazzo | 2006-09-10 18:23:49 +0200 (Sun, 10 Sep 2006) | 15 lines
- Don't strip empty lines from documentation comment blocks.
Without the patch, a block such::
#: frobnication factor
#:
#: :type: ``int``
is transformed in the string::
frobnication factor
:type: ``int``
that is a docstring error (the field is not recognized).
........
r1380 | dvarrazzo | 2006-09-10 18:31:38 +0200 (Sun, 10 Sep 2006) | 6 lines
- 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.
........
r1381 | edloper | 2006-09-11 00:43:02 +0200 (Mon, 11 Sep 2006) | 4 lines
- When checking keyword args to APIDoc constructor, don't complain
about args that begin with '_'.
- Minor docstring changes
........
r1382 | edloper | 2006-09-11 00:43:51 +0200 (Mon, 11 Sep 2006) | 3 lines
- When building stdlib docs, don't include any graphs or source code --
the quota on sourceforge won't allow enough space for them. :(
........
r1383 | dvarrazzo | 2006-09-11 14:34:31 +0200 (Mon, 11 Sep 2006) | 6 lines
- Fixed docutils version check.
E.g. when docutils.__version__ == '0.4'
=> [ 0, 4 ] < [ 0, 4, 0 ] == True
=> Deprecation warnings are raised.
........
r1384 | dvarrazzo | 2006-09-11 15:42:10 +0200 (Mon, 11 Sep 2006) | 9 lines
- Introspecter doesn't document the object resulting from a "from __future__"
statement.
Because the check deals with the implementation of a quasi-magic module,
guard from unexpected implementation changes. In such case, issue a single
warning and don't barf.
The current implementation is tested with Python 2.4.3.
........
r1385 | dvarrazzo | 2006-09-11 15:45:12 +0200 (Mon, 11 Sep 2006) | 2 lines
- Replaced a "!= None" test with an "is not None"
........
r1386 | dvarrazzo | 2006-09-11 18:12:51 +0200 (Mon, 11 Sep 2006) | 4 lines
- Fixed parsing of import statements in the form::
from mod import a as b
........
r1387 | dvarrazzo | 2006-09-13 05:04:00 +0200 (Wed, 13 Sep 2006) | 3 lines
- Added a filter to remove the class vtable generated by Pyrex for
extension modules.
........
r1388 | dvarrazzo | 2006-09-13 05:24:38 +0200 (Wed, 13 Sep 2006) | 2 lines
- member_descriptor attributes are recognized as property.
........
Modified Paths:
--------------
branches/exp-args_in_class/epydoc/Makefile
branches/exp-args_in_class/epydoc/doc/doctest/index.html
branches/exp-args_in_class/epydoc/doc/fields.html
branches/exp-args_in_class/epydoc/src/epydoc/apidoc.py
branches/exp-args_in_class/epydoc/src/epydoc/docbuilder.py
branches/exp-args_in_class/epydoc/src/epydoc/docintrospecter.py
branches/exp-args_in_class/epydoc/src/epydoc/docparser.py
branches/exp-args_in_class/epydoc/src/epydoc/docwriter/html.py
branches/exp-args_in_class/epydoc/src/epydoc/markup/restructuredtext.py
branches/exp-args_in_class/epydoc/src/epydoc/test/docbuilder.doctest
branches/exp-args_in_class/epydoc/src/epydoc/test/docintrospecter.doctest
branches/exp-args_in_class/epydoc/src/epydoc/test/docparser.doctest
Property Changed:
----------------
branches/exp-args_in_class/
Property changes on: branches/exp-args_in_class
___________________________________________________________________
Name: svnmerge-integrated
- /trunk:1-1375
+ /trunk:1-1388
Modified: branches/exp-args_in_class/epydoc/Makefile
===================================================================
--- branches/exp-args_in_class/epydoc/Makefile 2006-09-13 03:24:38 UTC (rev 1388)
+++ branches/exp-args_in_class/epydoc/Makefile 2006-09-14 21:37:38 UTC (rev 1389)
@@ -235,7 +235,7 @@
mkdir -p $(HTML_STDLIB)
@echo "Building stdlib html docs..."
@$(EPYDOC) -o $(HTML_STDLIB) --css white --name $(SLNAME) \
- --url $(SLURL) --debug --graph classtree --debug \
+ --url $(SLURL) --debug --no-sourcecode --debug \
--show-imports $(SLBUILTINS) $(SLFILES)
touch .stdlib-html.up2date
Modified: branches/exp-args_in_class/epydoc/doc/doctest/index.html
===================================================================
--- branches/exp-args_in_class/epydoc/doc/doctest/index.html 2006-09-13 03:24:38 UTC (rev 1388)
+++ branches/exp-args_in_class/epydoc/doc/doctest/index.html 2006-09-14 21:37:38 UTC (rev 1389)
@@ -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: branches/exp-args_in_class/epydoc/doc/fields.html
===================================================================
--- branches/exp-args_in_class/epydoc/doc/fields.html 2006-09-13 03:24:38 UTC (rev 1388)
+++ branches/exp-args_in_class/epydoc/doc/fields.html 2006-09-14 21:37:38 UTC (rev 1389)
@@ -262,7 +262,7 @@
fields may be used if an object has multiple authors.</td></tr>
<tr><td width="10%" align="left" valign="top">
- <code>@<b>organiation</b>:</code> ... </td><td> The
+ <code>@<b>organization</b>:</code> ... </td><td> The
organization that created or maintains an
object. </td></tr>
Modified: branches/exp-args_in_class/epydoc/src/epydoc/apidoc.py
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/apidoc.py 2006-09-13 03:24:38 UTC (rev 1388)
+++ branches/exp-args_in_class/epydoc/src/epydoc/apidoc.py 2006-09-14 21:37:38 UTC (rev 1389)
@@ -374,7 +374,7 @@
"""
if epydoc.DEBUG:
for key in kwargs:
- if not hasattr(self.__class__, key):
+ if key[0] != '_' and not hasattr(self.__class__, key):
raise TypeError('%s got unexpected arg %r' %
(self.__class__.__name__, key))
self.__dict__.update(kwargs)
@@ -850,7 +850,7 @@
names, and the values are lists of C{VariableDoc}s. The order
that groups should be listed in should be taken from
L{group_specs}.
- @type: C{dict} from C{str} to C{list} of L{APIDoc}"""
+ @type: C{dict} from C{str} to C{list} of L{VariableDoc}"""
#} end of group "information about variables"
def __init__(self, **kwargs):
@@ -996,7 +996,7 @@
names, and the values are lists of C{ModuleDoc}s. The order
that groups should be listed in should be taken from
L{group_specs}.
- @type: C{dict} from C{str} to C{list} of L{APIDoc}"""
+ @type: C{dict} from C{str} to C{list} of L{ModuleDoc}"""
#{ Information about Packages
package = UNKNOWN
"""@ivar: API documentation for the module's containing package.
Modified: branches/exp-args_in_class/epydoc/src/epydoc/docbuilder.py
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/docbuilder.py 2006-09-13 03:24:38 UTC (rev 1388)
+++ branches/exp-args_in_class/epydoc/src/epydoc/docbuilder.py 2006-09-14 21:37:38 UTC (rev 1389)
@@ -191,6 +191,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()
Modified: branches/exp-args_in_class/epydoc/src/epydoc/docintrospecter.py
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/docintrospecter.py 2006-09-13 03:24:38 UTC (rev 1388)
+++ branches/exp-args_in_class/epydoc/src/epydoc/docintrospecter.py 2006-09-14 21:37:38 UTC (rev 1389)
@@ -246,7 +246,7 @@
# Create a VariableDoc for the child, and introspect its
# value if it's defined in this module.
container = get_containing_module(child)
- if container != None and container == module_doc.canonical_name:
+ if container is not None and container == module_doc.canonical_name:
# Local variable.
child_val_doc = introspect_docs(child, context=module_doc)
child_var_doc = VariableDoc(name=child_name,
@@ -255,6 +255,10 @@
container=module_doc,
docs_extracted_by='introspecter')
elif container is None or module_doc.canonical_name is UNKNOWN:
+
+ # Don't introspect stuff "from __future__"
+ if is_future_feature(child): continue
+
# Possibly imported variable.
child_val_doc = introspect_docs(child, context=module_doc)
child_var_doc = VariableDoc(name=child_name,
@@ -295,7 +299,8 @@
#: A list of class variables that should not be included in a
#: class's API documentation.
UNDOCUMENTED_CLASS_VARS = (
- '__doc__', '__module__', '__dict__', '__weakref__', '__slots__')
+ '__doc__', '__module__', '__dict__', '__weakref__', '__slots__',
+ '__pyx_vtable__')
def introspect_class(cls, class_doc):
"""
@@ -483,6 +488,31 @@
"""
return isinstance(object, (TypeType, ClassType))
+__future_check_works = None
+
+def is_future_feature(object):
+ """
+ Return True if C{object} results from a C{from __future__ import feature"}
+ statement.
+ """
+ # Guard from unexpected implementation changes of the __future__ module.
+ global __future_check_works
+ if __future_check_works is not None:
+ if __future_check_works:
+ import __future__
+ return isinstance(object, __future__._Feature)
+ else:
+ return False
+ else:
+ __future_check_works = True
+ try:
+ return is_future_feature(object)
+ except:
+ __future_check_works = False
+ log.warning("Troubles inspecting __future__. Python implementation"
+ " may have been changed.")
+ return False
+
def get_docstring(value):
"""
Return the docstring for the given value; or C{None} if it
@@ -685,15 +715,26 @@
register_introspecter(inspect.isroutine, introspect_routine, priority=28)
register_introspecter(is_property, introspect_property, priority=30)
+# Register getset_descriptor as a property
try:
import array
- attribute = type(array.array.typecode)
+ getset_type = type(array.array.typecode)
del array
- def is_attribute(v): return isinstance(v, attribute)
- register_introspecter(is_attribute, introspect_property, priority=32)
+ def is_getset(v): return isinstance(v, getset_type)
+ register_introspecter(is_getset, introspect_property, priority=32)
except:
pass
+# Register member_descriptor as a property
+try:
+ import datetime
+ member_type = type(datetime.timedelta.days)
+ del datetime
+ def is_member(v): return isinstance(v, member_type)
+ register_introspecter(is_member, introspect_property, priority=34)
+except:
+ pass
+
#////////////////////////////////////////////////////////////
# Import support
#////////////////////////////////////////////////////////////
Modified: branches/exp-args_in_class/epydoc/src/epydoc/docparser.py
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/docparser.py 2006-09-13 03:24:38 UTC (rev 1388)
+++ branches/exp-args_in_class/epydoc/src/epydoc/docparser.py 2006-09-14 21:37:38 UTC (rev 1389)
@@ -157,7 +157,7 @@
"""
#{ Configuration Constants: Comment docstrings
-COMMENT_DOCSTRING_MARKER = '#: '
+COMMENT_DOCSTRING_MARKER = '#:'
"""The prefix used to mark comments that contain attribute
docstrings for variables."""
@@ -577,6 +577,8 @@
elif toktype == tokenize.COMMENT:
if toktext.startswith(COMMENT_DOCSTRING_MARKER):
comment_line = toktext[len(COMMENT_DOCSTRING_MARKER):].rstrip()
+ if comment_line.startswith(" "):
+ comment_line = comment_line[1:]
comments.append( [comment_line, srow])
elif toktext.startswith(START_GROUP_MARKER):
start_group = toktext[len(START_GROUP_MARKER):].strip()
@@ -844,12 +846,24 @@
# >>> from os.path import join, split
else:
src_name = parse_dotted_name(lhs)
- for elt in rhs:
- if elt != (token.OP, ','):
- var_name = parse_name(elt)
+ parts = split_on(rhs, (token.OP, ','))
+ for part in parts:
+ # from m import x
+ if len(part) == 1:
+ var_name = parse_name(part[0])
_import_var_as(DottedName(src_name, var_name),
var_name, parent_docs)
-
+
+ # from m import x as y
+ elif len(part) == 3 and part[1] == (token.NAME, 'as'):
+ orig_name = parse_name(part[0])
+ var_name = parse_name(part[2])
+ _import_var_as(DottedName(src_name, orig_name),
+ var_name, parent_docs)
+
+ else:
+ ParseError("Bad from-import")
+
def _process_fromstar_import(src, parent_docs):
"""
Handle a statement of the form:
Modified: branches/exp-args_in_class/epydoc/src/epydoc/docwriter/html.py
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/docwriter/html.py 2006-09-13 03:24:38 UTC (rev 1388)
+++ branches/exp-args_in_class/epydoc/src/epydoc/docwriter/html.py 2006-09-14 21:37:38 UTC (rev 1389)
@@ -2498,8 +2498,11 @@
else:
return '??'
else:
- context_name = context.canonical_name
- return str(doc.canonical_name.contextualize(context_name))
+ if context is UNKNOWN:
+ return str(doc.canonical_name)
+ else:
+ context_name = context.canonical_name
+ return str(doc.canonical_name.contextualize(context_name))
#////////////////////////////////////////////////////////////
#{ Function Signatures
Modified: branches/exp-args_in_class/epydoc/src/epydoc/markup/restructuredtext.py
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/markup/restructuredtext.py 2006-09-13 03:24:38 UTC (rev 1388)
+++ branches/exp-args_in_class/epydoc/src/epydoc/markup/restructuredtext.py 2006-09-14 21:37:38 UTC (rev 1389)
@@ -215,7 +215,9 @@
# depending on the version of docutils that's being used, because
# the default_transforms attribute was deprecated & replaced by
# get_transforms().
- if [int(v) for v in docutils.__version__.split('.')] < [0,4,0]:
+ version = [int(v) for v in docutils.__version__.split('.')]
+ version += [ 0 ] * (3 - len(version))
+ if version < [0,4,0]:
default_transforms = list(StandaloneReader.default_transforms)
try: default_transforms.remove(docutils.transforms.frontmatter.DocInfo)
except ValueError: pass
@@ -223,6 +225,7 @@
def get_transforms(self):
return [t for t in StandaloneReader.get_transforms(self)
if t != docutils.transforms.frontmatter.DocInfo]
+ del version
def __init__(self, errors):
self._errors = errors
Modified: branches/exp-args_in_class/epydoc/src/epydoc/test/docbuilder.doctest
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/test/docbuilder.doctest 2006-09-13 03:24:38 UTC (rev 1388)
+++ branches/exp-args_in_class/epydoc/src/epydoc/test/docbuilder.doctest 2006-09-14 21:37:38 UTC (rev 1389)
@@ -3,31 +3,26 @@
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 `introspect` argument gives the
-name of a variable in the module whose value should be introspected,
-instead of introspecting the whole module.
+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='', introspect=None, exclude=''):
+ >>> 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()
- ... # Import it.
- ... sys.path.insert(0, tmp_dir)
- ... if introspect is None:
- ... import epydoc_test as val
- ... else:
- ... exec("from epydoc_test import %s as val" % introspect)
- ... del sys.path[0]
- ... # Introspect it.
- ... val_doc = build_doc(val)
+ ... # 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)
@@ -42,7 +37,92 @@
... 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'
+
+ >>> runbuilder(s="""
+ ... from __future__ import division
+ ... from re import match
+ ... """,
+ ... attribs='variables value')
+
+
Specifying constructor signature in class docstring
===================================================
Modified: branches/exp-args_in_class/epydoc/src/epydoc/test/docintrospecter.doctest
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/test/docintrospecter.doctest 2006-09-13 03:24:38 UTC (rev 1388)
+++ branches/exp-args_in_class/epydoc/src/epydoc/test/docintrospecter.doctest 2006-09-14 21:37:38 UTC (rev 1389)
@@ -520,6 +520,16 @@
+- ModuleDoc for re [4]
+- variables = {}
+ >>> runintrospecter(s="""
+ ... from __future__ import division
+ ... from re import match
+ ... """,
+ ... attribs='variables value')
+ ModuleDoc for epydoc_test [0]
+ +- variables
+ +- match => VariableDoc for epydoc_test.match [1]
+ +- value
+ +- ValueDoc for sre.match [2]
Unicode
=======
Modified: branches/exp-args_in_class/epydoc/src/epydoc/test/docparser.doctest
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/test/docparser.doctest 2006-09-13 03:24:38 UTC (rev 1388)
+++ branches/exp-args_in_class/epydoc/src/epydoc/test/docparser.doctest 2006-09-14 21:37:38 UTC (rev 1389)
@@ -710,6 +710,21 @@
+- is_imported = True
+- value = <UNKNOWN>
+ >>> runparser(s="""
+ ... from re import match as much, split, sub as scuba
+ ... """,
+ ... attribs='variables name imported_from')
+ ModuleDoc for test [0]
+ +- variables
+ +- much => VariableDoc for test.much [1]
+ | +- imported_from = DottedName(u're', u'match')
+ | +- name = u'much'
+ +- scuba => VariableDoc for test.scuba [2]
+ | +- imported_from = DottedName(u're', u'sub')
+ | +- name = u'scuba'
+ +- split => VariableDoc for test.split [3]
+ +- imported_from = DottedName(u're', u'split')
+ +- name = u'split'
Unicode
=======
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
