Thread: [Epydoc-commits] SF.net SVN: epydoc: [1376] branches/exp-args_in_class
Brought to you by:
edloper
From: <dva...@us...> - 2006-09-08 20:53:56
|
Revision: 1376 http://svn.sourceforge.net/epydoc/?rev=1376&view=rev Author: dvarrazzo Date: 2006-09-08 13:53:48 -0700 (Fri, 08 Sep 2006) Log Message: ----------- Merged revisions 1371-1375 via svnmerge from https://svn.sourceforge.net/svnroot/epydoc/trunk ........ r1375 | dvarrazzo | 2006-09-08 22:39:09 +0200 (Fri, 08 Sep 2006) | 2 lines - Dropped use of sort_by_name keyword in DocIndex.reachable_valdoc() ........ Modified Paths: -------------- branches/exp-args_in_class/epydoc/src/epydoc/docbuilder.py Property Changed: ---------------- branches/exp-args_in_class/ Property changes on: branches/exp-args_in_class ___________________________________________________________________ Name: svnmerge-integrated - /trunk:1-1370 + /trunk:1-1375 Modified: branches/exp-args_in_class/epydoc/src/epydoc/docbuilder.py =================================================================== --- branches/exp-args_in_class/epydoc/src/epydoc/docbuilder.py 2006-09-08 20:39:09 UTC (rev 1375) +++ branches/exp-args_in_class/epydoc/src/epydoc/docbuilder.py 2006-09-08 20:53:48 UTC (rev 1376) @@ -162,9 +162,8 @@ # their targets. if parse: log.start_progress('Linking imported variables') - valdocs = docindex.reachable_valdocs(sort_by_name=True, imports=False, - submodules=False, packages=False, - subclasses=False) + valdocs = sorted(docindex.reachable_valdocs( + imports=False, submodules=False, packages=False, subclasses=False)) for i, val_doc in enumerate(valdocs): _report_valdoc_progress(i, val_doc, valdocs) link_imports(val_doc, docindex) @@ -179,13 +178,12 @@ # Parse the docstrings for each object. log.start_progress('Parsing docstrings') - valdocs = docindex.reachable_valdocs(sort_by_name=True, imports=False, - submodules=False, packages=False, - subclasses=False) - # Sort according to dotted name, so __init__ docstrings are parsed after + # Sorting here is important to parse __init__ docstrings after matching # class docstrings, allowing constructor parameters to be specified in the # latters - for i, val_doc in enumerate(sorted(valdocs)): + valdocs = sorted(docindex.reachable_valdocs( + imports=False, submodules=False, packages=False, subclasses=False)) + for i, val_doc in enumerate(valdocs): _report_valdoc_progress(i, val_doc, valdocs) # the value's docstring parse_docstring(val_doc, docindex) This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
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. |