epydoc-commits Mailing List for Python API documentation generation tool (Page 18)
Brought to you by:
edloper
Menu
▾
▴
epydoc-commits — CVS commit logs for the epydoc project
You can subscribe to this list here.
| 2006 |
Jan
|
Feb
|
Mar
|
Apr
(77) |
May
|
Jun
(6) |
Jul
(8) |
Aug
(91) |
Sep
(67) |
Oct
(4) |
Nov
|
Dec
(1) |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2007 |
Jan
(17) |
Feb
(135) |
Mar
(25) |
Apr
|
May
(1) |
Jun
(1) |
Jul
(7) |
Aug
|
Sep
(62) |
Oct
(1) |
Nov
(3) |
Dec
|
| 2008 |
Jan
(40) |
Feb
(102) |
Mar
(5) |
Apr
|
May
|
Jun
|
Jul
|
Aug
|
Sep
|
Oct
|
Nov
|
Dec
|
| 2009 |
Jan
|
Feb
(2) |
Mar
|
Apr
|
May
|
Jun
|
Jul
|
Aug
|
Sep
|
Oct
|
Nov
|
Dec
|
|
From: <dva...@us...> - 2006-09-11 13:45:24
|
Revision: 1385
http://svn.sourceforge.net/epydoc/?rev=1385&view=rev
Author: dvarrazzo
Date: 2006-09-11 06:45:12 -0700 (Mon, 11 Sep 2006)
Log Message:
-----------
- Replaced a "!= None" test with an "is not None"
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docintrospecter.py
Modified: trunk/epydoc/src/epydoc/docintrospecter.py
===================================================================
--- trunk/epydoc/src/epydoc/docintrospecter.py 2006-09-11 13:42:10 UTC (rev 1384)
+++ trunk/epydoc/src/epydoc/docintrospecter.py 2006-09-11 13:45:12 UTC (rev 1385)
@@ -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,
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2006-09-11 13:42:21
|
Revision: 1384
http://svn.sourceforge.net/epydoc/?rev=1384&view=rev
Author: dvarrazzo
Date: 2006-09-11 06:42:10 -0700 (Mon, 11 Sep 2006)
Log Message:
-----------
- 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.
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docintrospecter.py
trunk/epydoc/src/epydoc/test/docintrospecter.doctest
Modified: trunk/epydoc/src/epydoc/docintrospecter.py
===================================================================
--- trunk/epydoc/src/epydoc/docintrospecter.py 2006-09-11 12:34:31 UTC (rev 1383)
+++ trunk/epydoc/src/epydoc/docintrospecter.py 2006-09-11 13:42:10 UTC (rev 1384)
@@ -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,
@@ -483,6 +487,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
Modified: trunk/epydoc/src/epydoc/test/docintrospecter.doctest
===================================================================
--- trunk/epydoc/src/epydoc/test/docintrospecter.doctest 2006-09-11 12:34:31 UTC (rev 1383)
+++ trunk/epydoc/src/epydoc/test/docintrospecter.doctest 2006-09-11 13:42:10 UTC (rev 1384)
@@ -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
=======
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2006-09-11 12:34:44
|
Revision: 1383
http://svn.sourceforge.net/epydoc/?rev=1383&view=rev
Author: dvarrazzo
Date: 2006-09-11 05:34:31 -0700 (Mon, 11 Sep 2006)
Log Message:
-----------
- Fixed docutils version check.
E.g. when docutils.__version__ == '0.4'
=> [ 0, 4 ] < [ 0, 4, 0 ] == True
=> Deprecation warnings are raised.
Modified Paths:
--------------
trunk/epydoc/src/epydoc/markup/restructuredtext.py
Modified: trunk/epydoc/src/epydoc/markup/restructuredtext.py
===================================================================
--- trunk/epydoc/src/epydoc/markup/restructuredtext.py 2006-09-10 22:43:51 UTC (rev 1382)
+++ trunk/epydoc/src/epydoc/markup/restructuredtext.py 2006-09-11 12:34:31 UTC (rev 1383)
@@ -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
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2006-09-10 22:43:55
|
Revision: 1382
http://svn.sourceforge.net/epydoc/?rev=1382&view=rev
Author: edloper
Date: 2006-09-10 15:43:51 -0700 (Sun, 10 Sep 2006)
Log Message:
-----------
- When building stdlib docs, don't include any graphs or source code --
the quota on sourceforge won't allow enough space for them. :(
Modified Paths:
--------------
trunk/epydoc/Makefile
Modified: trunk/epydoc/Makefile
===================================================================
--- trunk/epydoc/Makefile 2006-09-10 22:43:02 UTC (rev 1381)
+++ trunk/epydoc/Makefile 2006-09-10 22:43:51 UTC (rev 1382)
@@ -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
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2006-09-10 22:43:05
|
Revision: 1381
http://svn.sourceforge.net/epydoc/?rev=1381&view=rev
Author: edloper
Date: 2006-09-10 15:43:02 -0700 (Sun, 10 Sep 2006)
Log Message:
-----------
- When checking keyword args to APIDoc constructor, don't complain
about args that begin with '_'.
- Minor docstring changes
Modified Paths:
--------------
trunk/epydoc/src/epydoc/apidoc.py
Modified: trunk/epydoc/src/epydoc/apidoc.py
===================================================================
--- trunk/epydoc/src/epydoc/apidoc.py 2006-09-10 16:31:38 UTC (rev 1380)
+++ trunk/epydoc/src/epydoc/apidoc.py 2006-09-10 22:43:02 UTC (rev 1381)
@@ -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.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2006-09-10 16:31:52
|
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.
|
|
From: <dva...@us...> - 2006-09-10 16:24:00
|
Revision: 1379
http://svn.sourceforge.net/epydoc/?rev=1379&view=rev
Author: dvarrazzo
Date: 2006-09-10 09:23:49 -0700 (Sun, 10 Sep 2006)
Log Message:
-----------
- 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).
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docparser.py
Modified: trunk/epydoc/src/epydoc/docparser.py
===================================================================
--- trunk/epydoc/src/epydoc/docparser.py 2006-09-10 15:16:41 UTC (rev 1378)
+++ trunk/epydoc/src/epydoc/docparser.py 2006-09-10 16:23:49 UTC (rev 1379)
@@ -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()
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2006-09-10 15:16:47
|
Revision: 1378
http://svn.sourceforge.net/epydoc/?rev=1378&view=rev
Author: dvarrazzo
Date: 2006-09-10 08:16:41 -0700 (Sun, 10 Sep 2006)
Log Message:
-----------
Fixed typo.
Modified Paths:
--------------
trunk/epydoc/doc/fields.html
Modified: trunk/epydoc/doc/fields.html
===================================================================
--- trunk/epydoc/doc/fields.html 2006-09-10 14:29:31 UTC (rev 1377)
+++ trunk/epydoc/doc/fields.html 2006-09-10 15:16:41 UTC (rev 1378)
@@ -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>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2006-09-10 14:29:37
|
Revision: 1377
http://svn.sourceforge.net/epydoc/?rev=1377&view=rev
Author: edloper
Date: 2006-09-10 07:29:31 -0700 (Sun, 10 Sep 2006)
Log Message:
-----------
- 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.)
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docwriter/html.py
Modified: trunk/epydoc/src/epydoc/docwriter/html.py
===================================================================
--- trunk/epydoc/src/epydoc/docwriter/html.py 2006-09-08 20:53:48 UTC (rev 1376)
+++ trunk/epydoc/src/epydoc/docwriter/html.py 2006-09-10 14:29:31 UTC (rev 1377)
@@ -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
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
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-08 20:39:15
|
Revision: 1375
http://svn.sourceforge.net/epydoc/?rev=1375&view=rev
Author: dvarrazzo
Date: 2006-09-08 13:39:09 -0700 (Fri, 08 Sep 2006)
Log Message:
-----------
- Dropped use of sort_by_name keyword in DocIndex.reachable_valdoc()
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docbuilder.py
Modified: trunk/epydoc/src/epydoc/docbuilder.py
===================================================================
--- trunk/epydoc/src/epydoc/docbuilder.py 2006-09-08 15:40:13 UTC (rev 1374)
+++ trunk/epydoc/src/epydoc/docbuilder.py 2006-09-08 20:39:09 UTC (rev 1375)
@@ -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,9 +178,8 @@
# 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)
+ 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
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2006-09-08 15:40:22
|
Revision: 1374
http://svn.sourceforge.net/epydoc/?rev=1374&view=rev
Author: dvarrazzo
Date: 2006-09-08 08:40:13 -0700 (Fri, 08 Sep 2006)
Log Message:
-----------
- __init__ signature can be described in the class docstring also when there
is no __init__.__doc__ at all.
- parse_function_signature() can receive two arguments: one whose docstring is
to be parsed and one to be populated. So the constructor signature can be
parsed from the class docstring.
- Dropped generation of variables when there is a type w/o matching var.
The issue is still to be defined consistently anyway.
Modified Paths:
--------------
branches/exp-args_in_class/epydoc/src/epydoc/docstringparser.py
Added Paths:
-----------
branches/exp-args_in_class/epydoc/src/epydoc/test/docbuilder.doctest
Modified: branches/exp-args_in_class/epydoc/src/epydoc/docstringparser.py
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/docstringparser.py 2006-09-08 10:38:55 UTC (rev 1373)
+++ branches/exp-args_in_class/epydoc/src/epydoc/docstringparser.py 2006-09-08 15:40:13 UTC (rev 1374)
@@ -174,8 +174,12 @@
initialize_api_doc(api_doc)
# If there's no docstring, then there's nothing more to do.
+ # ...except in a case: an __init__ function that is to receive some
+ # documentation from the class docstring
if (api_doc.docstring in (None, UNKNOWN)):
- return
+ if not (isinstance(api_doc, RoutineDoc)
+ and api_doc.canonical_name[-1] == '__init__'):
+ return
# Remove leading indentation from the docstring.
api_doc.docstring = unindent_docstring(api_doc.docstring)
@@ -184,6 +188,10 @@
# overrides any signature we got via introspection/parsing.
if isinstance(api_doc, RoutineDoc):
parse_function_signature(api_doc)
+ elif isinstance(api_doc, ClassDoc):
+ initvar = api_doc.variables.get('__init__')
+ if initvar:
+ parse_function_signature(initvar.value, api_doc)
# Parse the docstring. Any errors encountered are stored as
# `ParseError` objects in the errors list.
@@ -694,9 +702,16 @@
def set_var_type(api_doc, ident, descr):
if ident not in api_doc.variables:
- api_doc.variables[ident] = VariableDoc(
- container=api_doc, name=ident,
- canonical_name=api_doc.canonical_name+ident)
+ # [xx] If there is a type w/o matching var, this would create
+ # a new var. The behavior is to be decied consistently also in other
+ # places in this sources (grep for [xx]).
+ # Currently disable the creation or else each "type" used in the
+ # class docstring to describe an __init__ parameter also generates
+ # an extra class variable.
+ #api_doc.variables[ident] = VariableDoc(
+ #container=api_doc, name=ident,
+ #canonical_name=api_doc.canonical_name+ident)
+ return
var_doc = api_doc.variables[ident]
if var_doc.type_descr not in (None, UNKNOWN):
@@ -740,7 +755,7 @@
# [xx] copied from inspect.getdoc(); we can't use inspect.getdoc()
# itself, since it expects an object, not a string.
- if docstring == '': return ''
+ if not docstring: return ''
lines = docstring.expandtabs().split('\n')
# Find minimum indentation of any non-blank lines after first line.
@@ -823,7 +838,7 @@
"""A regular expression that is used to extract signatures from
docstrings."""
-def parse_function_signature(func_doc):
+def parse_function_signature(func_doc, doc_source=None):
"""
Construct the signature for a builtin function or method from
its docstring. If the docstring uses the standard convention
@@ -833,15 +848,26 @@
Otherwise, the signature will be set to a single varargs
variable named C{"..."}.
+ @param func_doc: The target object where to store parsed signature. Also
+ container of the docstring to parse if doc_source is C{None}
+ @type L{RoutineDoc}
+ @param doc_source: Contains the docstring to parse. If C{None}, parse
+ L{func_doc} docstring instead
+ @type L{APIDoc}
@rtype: C{None}
"""
+ if doc_source is None:
+ doc_source = func_doc
+
# If there's no docstring, then don't do anything.
- if not func_doc.docstring: return False
+ if not doc_source.docstring: return False
- m = _SIGNATURE_RE.match(func_doc.docstring)
+ m = _SIGNATURE_RE.match(doc_source.docstring)
if m is None: return False
# Do I want to be this strict?
+ # Notice that __init__ must match the class name instead, if the signature
+ # comes from the class docstring
# if not (m.group('func') == func_doc.canonical_name[-1] or
# '_'+m.group('func') == func_doc.canonical_name[-1]):
# log.warning("Not extracting function signature from %s's "
@@ -900,7 +926,7 @@
func_doc.posarg_defaults.insert(0, None)
# Remove the signature from the docstring.
- func_doc.docstring = func_doc.docstring[m.end():]
+ doc_source.docstring = doc_source.docstring[m.end():]
# We found a signature.
return True
Added: branches/exp-args_in_class/epydoc/src/epydoc/test/docbuilder.doctest
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/test/docbuilder.doctest (rev 0)
+++ branches/exp-args_in_class/epydoc/src/epydoc/test/docbuilder.doctest 2006-09-08 15:40:13 UTC (rev 1374)
@@ -0,0 +1,171 @@
+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 `introspect` argument gives the
+name of a variable in the module whose value should be introspected,
+instead of introspecting the whole module.
+
+ >>> import tempfile, re, os, os.path, textwrap, sys
+ >>> from epydoc.docbuilder import build_doc
+ >>> def runbuilder(s, attribs='', introspect=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)
+ ... # 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']
+
+
+Specifying constructor signature in class docstring
+===================================================
+
+The class signature can be specified in the class docstring instead of __init__
+
+ >>> runbuilder(s='''
+ ... class Foo:
+ ... """This is the object docstring
+ ...
+ ... @param a: init param.
+ ... @ivar a: instance var.
+ ... @type a: date
+ ... """
+ ... def __init__(self, a):
+ ... """The ctor docstring.
+ ...
+ ... @type a: str
+ ... """
+ ... pass
+ ... ''',
+ ... introspect="Foo",
+ ... attribs="variables name value "
+ ... "posargs vararg kwarg type arg_types arg_descrs")
+ ClassDoc for epydoc_test.Foo [0]
+ +- variables
+ +- __init__ => VariableDoc for epydoc_test.Foo.__init__ [1]
+ | +- name = '__init__'
+ | +- value
+ | +- RoutineDoc for epydoc_test.Foo.__init__ [2]
+ | +- arg_descrs = [([u'a'], ...
+ | +- arg_types = {u'a': ...
+ | +- kwarg = None
+ | +- posargs = ['self', 'a']
+ | +- vararg = None
+ +- a => VariableDoc for epydoc_test.Foo.a [3]
+ +- name = u'a'
+ +- value = <UNKNOWN>
+
+Also keywords arguments can be put in the constructor
+
+ >>> runbuilder(s='''
+ ... class Foo:
+ ... """This is the object docstring
+ ...
+ ... @keyword a: a kwarg.
+ ... @type a: str
+ ... """
+ ... def __init__(self, **kwargs):
+ ... """The ctor docstring.
+ ...
+ ... @type a: str
+ ... """
+ ... ''',
+ ... introspect="Foo",
+ ... attribs="variables name value "
+ ... "posargs vararg kwarg type arg_types arg_descrs")
+ ClassDoc for epydoc_test.Foo [0]
+ +- variables
+ +- __init__ => VariableDoc for epydoc_test.Foo.__init__ [1]
+ +- name = '__init__'
+ +- value
+ +- RoutineDoc for epydoc_test.Foo.__init__ [2]
+ +- arg_descrs = [([u'a'], ...
+ +- arg_types = {u'a': ...
+ +- kwarg = 'kwargs'
+ +- posargs = ['self']
+ +- vararg = None
+
+A missing docstring on the __init__ is not an issue.
+ >>> runbuilder(s='''
+ ... class Foo:
+ ... """This is the object docstring
+ ...
+ ... @param a: a param.
+ ... @type a: str
+ ... """
+ ... def __init__(self):
+ ... pass
+ ... ''',
+ ... introspect="Foo",
+ ... attribs="variables name value "
+ ... "posargs vararg kwarg type arg_types arg_descrs")
+ ClassDoc for epydoc_test.Foo [0]
+ +- variables
+ +- __init__ => VariableDoc for epydoc_test.Foo.__init__ [1]
+ +- name = '__init__'
+ +- value
+ +- RoutineDoc for epydoc_test.Foo.__init__ [2]
+ +- arg_descrs = [([u'a'], ...
+ +- arg_types = {u'a': ...
+ +- kwarg = None
+ +- posargs = ['self']
+ +- vararg = None
+
+Epydoc can also grok the constructor signature from the class docstring
+
+ >>> runbuilder(s='''
+ ... class Foo:
+ ... """Foo(x, y)
+ ...
+ ... A class to ship rockets in outer space.
+ ...
+ ... @param x: first param
+ ... @param y: second param
+ ... """
+ ... def __init__(self, a, b):
+ ... """__init__ doc"""
+ ... pass
+ ... ''',
+ ... introspect="Foo",
+ ... attribs="variables name value "
+ ... "posargs vararg kwarg type arg_types arg_descrs docstring")
+ ClassDoc for epydoc_test.Foo [0]
+ +- docstring = u'A class to ship rockets ...
+ +- variables
+ +- __init__ => VariableDoc for epydoc_test.Foo.__init__ [1]
+ +- docstring = <UNKNOWN>
+ +- name = '__init__'
+ +- value
+ +- RoutineDoc for epydoc_test.Foo.__init__ [2]
+ +- arg_descrs = [([u'x'], ...
+ +- arg_types = {}
+ +- docstring = u'__init__ doc'
+ +- kwarg = None
+ +- posargs = [u'x', u'y']
+ +- vararg = None
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2006-09-08 10:39:07
|
Revision: 1373
http://svn.sourceforge.net/epydoc/?rev=1373&view=rev
Author: dvarrazzo
Date: 2006-09-08 03:38:55 -0700 (Fri, 08 Sep 2006)
Log Message:
-----------
- Allow parameter-related fields in a class docstring: use them to extend the
matching __init__ docstring.
- Enforce docstring parsing in dotted name order to ensure class docstring
have already been parsed at __init__ docstring parsing time.
- "type" fields are used to specify both class/instance variables types and
constructor arguments types. In case a type is expressed in both class and
__init__ docstring, the latter wins (e.g. the __init__ may receive an arg,
parse it and store it in the instance state with the same name but different
type)
Modified Paths:
--------------
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/docstringparser.py
Modified: branches/exp-args_in_class/epydoc/src/epydoc/apidoc.py
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/apidoc.py 2006-09-08 10:28:10 UTC (rev 1372)
+++ branches/exp-args_in_class/epydoc/src/epydoc/apidoc.py 2006-09-08 10:38:55 UTC (rev 1373)
@@ -1118,6 +1118,10 @@
"""@ivar: API documentation for the class's known subclasses.
@type: C{list} of L{ClassDoc}"""
#}
+ init_args = UNKNOWN
+ """@ivar: Tags to be used as constructor documentation.
+ @type: C{list} of C{(tag, arg, descr)} tuples"""
+ #}
def apidoc_links(self, **filters):
val_docs = NamespaceDoc.apidoc_links(self, **filters)
Modified: branches/exp-args_in_class/epydoc/src/epydoc/docbuilder.py
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/docbuilder.py 2006-09-08 10:28:10 UTC (rev 1372)
+++ branches/exp-args_in_class/epydoc/src/epydoc/docbuilder.py 2006-09-08 10:38:55 UTC (rev 1373)
@@ -182,7 +182,10 @@
valdocs = docindex.reachable_valdocs(sort_by_name=True, imports=False,
submodules=False, packages=False,
subclasses=False)
- for i, val_doc in enumerate(valdocs):
+ # Sort according to dotted name, so __init__ docstrings are parsed after
+ # class docstrings, allowing constructor parameters to be specified in the
+ # latters
+ for i, val_doc in enumerate(sorted(valdocs)):
_report_valdoc_progress(i, val_doc, valdocs)
# the value's docstring
parse_docstring(val_doc, docindex)
Modified: branches/exp-args_in_class/epydoc/src/epydoc/docstringparser.py
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/docstringparser.py 2006-09-08 10:28:10 UTC (rev 1372)
+++ branches/exp-args_in_class/epydoc/src/epydoc/docstringparser.py 2006-09-08 10:38:55 UTC (rev 1373)
@@ -197,6 +197,37 @@
descr, fields = parsed_docstring.split_fields(parse_errors)
api_doc.descr = descr
+ # Handle the constructor fields that have been defined in the class
+ # docstring. This code assumes that a class docstring is parsed before
+ # the same class __init__ docstring.
+ if isinstance(api_doc, ClassDoc):
+ # Put aside param-related fields, which are to be considered as
+ # __init__ fields. "type" fields are to be used in both contexts.
+ param_tags = ('arg', 'argument', 'parameter', 'param',
+ 'kwarg', 'keyword', 'kwparam')
+ i = 0
+ while i < len(fields):
+ field = fields[i]
+ if field.tag() in param_tags:
+ api_doc.init_args.append(fields.pop(i))
+ continue
+ elif field.tag() == 'type':
+ api_doc.init_args.append(field)
+ i += 1
+
+ elif (isinstance(api_doc, RoutineDoc)
+ and api_doc.canonical_name[-1] == '__init__'):
+ # __init__ can receive arguments descriptions from the class docstring
+ # if a type is specified in both docstring, __init__ wins.
+ class_doc = docindex.get_valdoc(api_doc.canonical_name[:-1])
+ if class_doc is not None and class_doc.init_args is not UNKNOWN:
+ init_types = [ field.arg() for field in fields
+ if field.tag() == 'type' ]
+ for field in class_doc.init_args:
+ if field.tag() == 'type' and field.arg() in init_types:
+ continue
+ fields.append(field)
+
# Process fields
field_warnings = []
for field in fields:
@@ -234,6 +265,9 @@
api_doc.summary = None
if api_doc.metadata is UNKNOWN:
api_doc.metadata = []
+ if isinstance(api_doc, ClassDoc):
+ if api_doc.init_args is UNKNOWN:
+ api_doc.init_args = []
if isinstance(api_doc, RoutineDoc):
if api_doc.arg_descrs is UNKNOWN:
api_doc.arg_descrs = []
@@ -586,15 +620,24 @@
api_doc.return_type = descr
def process_arg_field(api_doc, docindex, tag, arg, descr):
- _check(api_doc, tag, arg, context=RoutineDoc, expect_arg=True)
+ _check(api_doc, tag, arg, context=(ClassDoc, RoutineDoc), expect_arg=True)
idents = re.split('[:;, ] *', arg)
- api_doc.arg_descrs.append( (idents, descr) )
- # Check to make sure that the documented parameter(s) are
- # actually part of the function signature.
- bad_params = ['"%s"' % i for i in idents if i not in api_doc.all_args()]
- if bad_params:
- raise ValueError(BAD_PARAM % (tag, ', '.join(bad_params)))
+ if isinstance(api_doc, RoutineDoc):
+ api_doc.arg_descrs.append( (idents, descr) )
+
+ # Check to make sure that the documented parameter(s) are
+ # actually part of the function signature.
+ bad_params = ['"%s"' % i for i in idents if i not in api_doc.all_args()]
+ if bad_params:
+ raise ValueError(BAD_PARAM % (tag, ', '.join(bad_params)))
+
+ elif isinstance(api_doc, ClassDoc):
+ api_doc.init_args.append( (tag, arg, descr) )
+
+ else:
+ assert False, "unexpected context"
+
def process_kwarg_field(api_doc, docindex, tag, arg, descr):
# [xx] these should -not- be checked if they exist..
# and listed separately or not??
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2006-09-08 10:28:17
|
Revision: 1372
http://svn.sourceforge.net/epydoc/?rev=1372&view=rev
Author: dvarrazzo
Date: 2006-09-08 03:28:10 -0700 (Fri, 08 Sep 2006)
Log Message:
-----------
Initialized merge tracking via "svnmerge" with revisions "1-1370" from
https://svn.sourceforge.net/svnroot/epydoc/trunk
Property Changed:
----------------
branches/exp-args_in_class/
Property changes on: branches/exp-args_in_class
___________________________________________________________________
Name: svnmerge-integrated
+ /trunk:1-1370
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2006-09-08 10:26:36
|
Revision: 1371
http://svn.sourceforge.net/epydoc/?rev=1371&view=rev
Author: dvarrazzo
Date: 2006-09-08 03:26:28 -0700 (Fri, 08 Sep 2006)
Log Message:
-----------
- Experimental branch: allow constructor parameters descriptions to be
expressed in the class docstring. This is mostly useful for extension types,
but is also a widespread docstring style.
Added Paths:
-----------
branches/exp-args_in_class/
Copied: branches/exp-args_in_class (from rev 1370, trunk)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2006-09-07 18:41:29
|
Revision: 1370
http://svn.sourceforge.net/epydoc/?rev=1370&view=rev
Author: dvarrazzo
Date: 2006-09-07 11:41:20 -0700 (Thu, 07 Sep 2006)
Log Message:
-----------
Documentation for __slots__ class variable is not generated.
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docintrospecter.py
trunk/epydoc/src/epydoc/docparser.py
trunk/epydoc/src/epydoc/test/docintrospecter.doctest
trunk/epydoc/src/epydoc/test/docparser.doctest
Modified: trunk/epydoc/src/epydoc/docintrospecter.py
===================================================================
--- trunk/epydoc/src/epydoc/docintrospecter.py 2006-09-07 15:56:54 UTC (rev 1369)
+++ trunk/epydoc/src/epydoc/docintrospecter.py 2006-09-07 18:41:20 UTC (rev 1370)
@@ -295,7 +295,7 @@
#: A list of class variables that should not be included in a
#: class's API documentation.
UNDOCUMENTED_CLASS_VARS = (
- '__doc__', '__module__', '__dict__', '__weakref__')
+ '__doc__', '__module__', '__dict__', '__weakref__', '__slots__')
def introspect_class(cls, class_doc):
"""
Modified: trunk/epydoc/src/epydoc/docparser.py
===================================================================
--- trunk/epydoc/src/epydoc/docparser.py 2006-09-07 15:56:54 UTC (rev 1369)
+++ trunk/epydoc/src/epydoc/docparser.py 2006-09-07 18:41:20 UTC (rev 1370)
@@ -1078,6 +1078,11 @@
if lhs_name is not None:
lhs_parent = get_lhs_parent(lhs_name, parent_docs)
if lhs_parent is None: continue
+
+ # Skip a special class variable.
+ if lhs_name[-1] == '__slots__':
+ continue
+
# Create the VariableDoc.
var_doc = VariableDoc(name=lhs_name[-1], value=rhs_val,
is_imported=False, is_alias=is_alias,
Modified: trunk/epydoc/src/epydoc/test/docintrospecter.doctest
===================================================================
--- trunk/epydoc/src/epydoc/test/docintrospecter.doctest 2006-09-07 15:56:54 UTC (rev 1369)
+++ trunk/epydoc/src/epydoc/test/docintrospecter.doctest 2006-09-07 18:41:20 UTC (rev 1370)
@@ -374,7 +374,28 @@
+- docstring = u'calculated base'
+- variables = {}
+Some class variable have a special meaning. The ``__slots__`` variable isn't
+very useful and should be discarded.
+ >>> runintrospecter(s="""
+ ... class Foo:
+ ... __slots__ = ['bar']
+ ... def __init__(self):
+ ... self.bar = 0
+ ... """,
+ ... attribs="variables name value")
+ ModuleDoc for epydoc_test [0]
+ +- variables
+ +- Foo => VariableDoc for epydoc_test.Foo [1]
+ +- name = 'Foo'
+ +- value
+ +- ClassDoc for epydoc_test.Foo [2]
+ +- variables
+ +- __init__ => VariableDoc for epydoc_test.Foo.__init__ [3]
+ +- name = '__init__'
+ +- value
+ +- RoutineDoc [4]
+
Delete Statements
=================
Modified: trunk/epydoc/src/epydoc/test/docparser.doctest
===================================================================
--- trunk/epydoc/src/epydoc/test/docparser.doctest 2006-09-07 15:56:54 UTC (rev 1369)
+++ trunk/epydoc/src/epydoc/test/docparser.doctest 2006-09-07 18:41:20 UTC (rev 1370)
@@ -229,6 +229,28 @@
+- GenericValueDoc [2]
+- parse_repr = u'33'
+Some class variable have a special meaning. The ``__slots__`` variable isn't
+very useful and should be discarded.
+
+ >>> runparser(s="""
+ ... class Foo:
+ ... __slots__ = ['bar']
+ ... def __init__(self):
+ ... self.bar = 0
+ ... """,
+ ... attribs="variables name value")
+ ModuleDoc for test [0]
+ +- variables
+ +- Foo => VariableDoc for test.Foo [1]
+ +- name = u'Foo'
+ +- value
+ +- ClassDoc for test.Foo [2]
+ +- variables
+ +- __init__ => VariableDoc for test.Foo.__init__ [3]
+ +- name = u'__init__'
+ +- value
+ +- RoutineDoc for test.Foo.__init__ [4]
+
Module Control Blocks
=====================
DocParser will look inside certain types of module-level control
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2006-09-07 15:56:57
|
Revision: 1369
http://svn.sourceforge.net/epydoc/?rev=1369&view=rev
Author: edloper
Date: 2006-09-07 08:56:54 -0700 (Thu, 07 Sep 2006)
Log Message:
-----------
- Check that type fields correspond to documented parameters *after*
all fields have been processed. (So the user can put a @type
before a corresponding @keyword.)
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docstringparser.py
Modified: trunk/epydoc/src/epydoc/docstringparser.py
===================================================================
--- trunk/epydoc/src/epydoc/docstringparser.py 2006-09-07 15:55:42 UTC (rev 1368)
+++ trunk/epydoc/src/epydoc/docstringparser.py 2006-09-07 15:56:54 UTC (rev 1369)
@@ -205,6 +205,10 @@
field.arg(), field.body())
except ValueError, e: field_warnings.append(str(e))
+ # Check to make sure that all type parameters correspond to
+ # some documented parameter.
+ check_type_fields(api_doc, field_warnings)
+
# Extract a summary
if api_doc.summary is None and api_doc.descr is not None:
api_doc.summary = api_doc.descr.summary()
@@ -526,13 +530,7 @@
if arg in api_doc.arg_types:
raise ValueError(REDEFINED % ('type for '+arg))
api_doc.arg_types[arg] = descr
- # Check to make sure that the documented parameter(s) are
- # actually part of the function signature.
- if arg not in api_doc.all_args():
- raise ValueError(BAD_PARAM % (tag, '"%s"' % arg))
- else:
- raise ValueError(BAD_CONTEXT % arg)
-
+
def process_var_field(api_doc, docindex, tag, arg, descr):
_check(api_doc, tag, arg, context=ModuleDoc, expect_arg=True)
for ident in re.split('[:;, ] *', arg):
@@ -626,6 +624,18 @@
#{ Helper Functions
######################################################################
+def check_type_fields(api_doc, field_warnings):
+ """Check to make sure that all type fields correspond to some
+ documented parameter; if not, append a warning to field_warnings."""
+ if isinstance(api_doc, RoutineDoc):
+ for arg in api_doc.arg_types:
+ if arg not in api_doc.all_args():
+ for args, descr in api_doc.arg_descrs:
+ if arg in args:
+ break
+ else:
+ field_warnings.append(BAD_PARAM % ('type', '"%s"' % arg))
+
def set_var_descr(api_doc, ident, descr):
if ident not in api_doc.variables:
api_doc.variables[ident] = VariableDoc(
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2006-09-07 15:55:46
|
Revision: 1368
http://svn.sourceforge.net/epydoc/?rev=1368&view=rev
Author: edloper
Date: 2006-09-07 08:55:42 -0700 (Thu, 07 Sep 2006)
Log Message:
-----------
- Docstring fixes
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docintrospecter.py
trunk/epydoc/src/epydoc/docwriter/html.py
trunk/epydoc/src/epydoc/log.py
Modified: trunk/epydoc/src/epydoc/docintrospecter.py
===================================================================
--- trunk/epydoc/src/epydoc/docintrospecter.py 2006-09-07 15:55:15 UTC (rev 1367)
+++ trunk/epydoc/src/epydoc/docintrospecter.py 2006-09-07 15:55:42 UTC (rev 1368)
@@ -758,7 +758,7 @@
"""
Given a name, return the corresponding value.
- @param globals: A namespace to check for the value, if there is no
+ @param globs: A namespace to check for the value, if there is no
module containing the named value. Defaults to __builtin__.
"""
name = DottedName(name)
Modified: trunk/epydoc/src/epydoc/docwriter/html.py
===================================================================
--- trunk/epydoc/src/epydoc/docwriter/html.py 2006-09-07 15:55:15 UTC (rev 1367)
+++ trunk/epydoc/src/epydoc/docwriter/html.py 2006-09-07 15:55:42 UTC (rev 1368)
@@ -208,7 +208,7 @@
Construct a new HTML writer, using the given documentation
index.
- @param docmap: The documentation index.
+ @param docindex: The documentation index.
@type prj_name: C{string}
@keyword prj_name: The name of the project. Defaults to
@@ -286,7 +286,7 @@
inherited objects are mixed in with non-inherited
objects. The default is 'grouped'.
@type include_source_code: C{boolean}
- @param include_sourc_ecode: If true, then generate colorized
+ @keyword include_source_code: If true, then generate colorized
source code files for each python module.
"""
self.docindex = docindex
Modified: trunk/epydoc/src/epydoc/log.py
===================================================================
--- trunk/epydoc/src/epydoc/log.py 2006-09-07 15:55:15 UTC (rev 1367)
+++ trunk/epydoc/src/epydoc/log.py 2006-09-07 15:55:42 UTC (rev 1368)
@@ -107,7 +107,7 @@
"""
Update the progress display.
- @param progress: A float from 0.0 to 1.0, indicating how much
+ @param percent: A float from 0.0 to 1.0, indicating how much
progress has been made.
@param message: A message indicating the most recent action
that contributed towards that progress.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2006-09-07 15:55:19
|
Revision: 1367
http://svn.sourceforge.net/epydoc/?rev=1367&view=rev
Author: edloper
Date: 2006-09-07 08:55:15 -0700 (Thu, 07 Sep 2006)
Log Message:
-----------
- Docstring fixes
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docbuilder.py
Modified: trunk/epydoc/src/epydoc/docbuilder.py
===================================================================
--- trunk/epydoc/src/epydoc/docbuilder.py 2006-09-07 15:54:59 UTC (rev 1366)
+++ trunk/epydoc/src/epydoc/docbuilder.py 2006-09-07 15:55:15 UTC (rev 1367)
@@ -369,11 +369,13 @@
Construct and return the API documentation for the python
module with the given filename.
- @param parent_doc: The C{ModuleDoc} of the containing package.
- If C{parent_doc} is not provided, then this method will
+ @param parent_docs: The C{ModuleDoc} of the containing package.
+ If C{parent_docs} is not provided, then this method will
check if the given filename is contained in a package; and
if so, it will construct a stub C{ModuleDoc} for the
- containing package(s).
+ containing package(s). C{parent_docs} is a tuple, where
+ the first element is the parent from introspection, and
+ the second element is the parent from parsing.
"""
# Record our progress.
modulename = os.path.splitext(os.path.split(filename)[1])[0]
@@ -589,7 +591,7 @@
@param attrib: The name of the attribute whose values are merged
by C{mergefunc}.
- @param mergefun: The merge function, whose sinature is:
+ @param mergefunc: The merge function, whose sinature is:
>>> def mergefunc(introspect_val, parse_val, precedence, cyclecheck, path):
... return calculate_merged_value(introspect_val, parse_val)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2006-09-07 15:55:04
|
Revision: 1366
http://svn.sourceforge.net/epydoc/?rev=1366&view=rev
Author: edloper
Date: 2006-09-07 08:54:59 -0700 (Thu, 07 Sep 2006)
Log Message:
-----------
- Docstring fixes
Modified Paths:
--------------
trunk/epydoc/src/epydoc/checker.py
Modified: trunk/epydoc/src/epydoc/checker.py
===================================================================
--- trunk/epydoc/src/epydoc/checker.py 2006-09-07 15:54:31 UTC (rev 1365)
+++ trunk/epydoc/src/epydoc/checker.py 2006-09-07 15:54:59 UTC (rev 1366)
@@ -167,14 +167,14 @@
contained by this C{DocChecker}'s C{DocIndex}. Any errors found
are printed to standard out.
- @param checks: The checks that should be run on the
+ @param check_sets: The checks that should be run on the
documentation. This value is constructed by or-ing
together the specifiers that indicate which objects should
be checked, and which checks should be run. See the
L{module description<checker>} for more information.
If no checks are specified, then a default set of checks
will be run.
- @type checks: C{int}
+ @type check_sets: C{int}
@return: True if no problems were found.
@rtype: C{boolean}
"""
@@ -288,9 +288,6 @@
@param doc: The documentation for the variable to check.
@type doc: L{APIDoc}
- @param check_type: Whether or not the variable's type should
- be checked. This is used to allow varargs and keyword
- parameters to have no type specified.
@rtype: C{None}
"""
if self._checks & DocChecker.VAR:
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2006-09-07 15:54:38
|
Revision: 1365
http://svn.sourceforge.net/epydoc/?rev=1365&view=rev
Author: edloper
Date: 2006-09-07 08:54:31 -0700 (Thu, 07 Sep 2006)
Log Message:
-----------
- Updated the description of RoutineDoc.arg_descrs to be more accurate
Modified Paths:
--------------
trunk/epydoc/src/epydoc/apidoc.py
Modified: trunk/epydoc/src/epydoc/apidoc.py
===================================================================
--- trunk/epydoc/src/epydoc/apidoc.py 2006-09-07 02:17:59 UTC (rev 1364)
+++ trunk/epydoc/src/epydoc/apidoc.py 2006-09-07 15:54:31 UTC (rev 1365)
@@ -1371,9 +1371,9 @@
#{ Information Extracted from Docstrings
arg_descrs = UNKNOWN
"""@ivar: A list of descriptions of the routine's
- arguments. Each element of this list is a tuple C{(arg,
- descr)}, where C{arg} is an argument name (or a tuple of
- of argument names); and C{descr} is a L{ParsedDocstring
+ arguments. Each element of this list is a tuple C{(args,
+ descr)}, where C{args} is a list of argument names; and
+ C{descr} is a L{ParsedDocstring
<epydoc.markup.ParsedDocstring>} describing the argument(s)
specified by C{arg}.
@type: C{list}"""
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2006-09-07 02:18:05
|
Revision: 1364
http://svn.sourceforge.net/epydoc/?rev=1364&view=rev
Author: edloper
Date: 2006-09-06 19:17:59 -0700 (Wed, 06 Sep 2006)
Log Message:
-----------
- Fixed bug in concatenating docstrings (descr may now be None)
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docstringparser.py
Modified: trunk/epydoc/src/epydoc/docstringparser.py
===================================================================
--- trunk/epydoc/src/epydoc/docstringparser.py 2006-09-06 23:47:17 UTC (rev 1363)
+++ trunk/epydoc/src/epydoc/docstringparser.py 2006-09-07 02:17:59 UTC (rev 1364)
@@ -545,7 +545,7 @@
isinstance(api_doc.container, ClassDoc)):
_check(api_doc, tag, arg, expect_arg=False)
api_doc.is_instvar = False
- api_doc.descr = api_doc.descr.concatenate(descr)
+ api_doc.descr = markup.ConcatenatedDocstring(api_doc.descr, descr)
api_doc.summary = descr.summary()
# Otherwise, @cvar should be used in a class.
@@ -563,7 +563,7 @@
_check(api_doc, tag, arg, expect_arg=False)
# require that there be no other descr?
api_doc.is_instvar = True
- api_doc.descr = api_doc.descr.concatenate(descr)
+ api_doc.descr = markup.ConcatenatedDocstring(api_doc.descr, descr)
api_doc.summary = descr.summary()
# Otherwise, @ivar should be used in a class.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2006-09-06 23:47:24
|
Revision: 1363
http://svn.sourceforge.net/epydoc/?rev=1363&view=rev
Author: edloper
Date: 2006-09-06 16:47:17 -0700 (Wed, 06 Sep 2006)
Log Message:
-----------
- When documenting the stdlib, ignore /idlelib/
- Clean up old profile.out file before making profile.out; and
clean up hotshot.out when we're done.
Modified Paths:
--------------
trunk/epydoc/Makefile
Modified: trunk/epydoc/Makefile
===================================================================
--- trunk/epydoc/Makefile 2006-09-06 23:46:28 UTC (rev 1362)
+++ trunk/epydoc/Makefile 2006-09-06 23:47:17 UTC (rev 1363)
@@ -206,11 +206,12 @@
> doc/epydocgui-man.html
profile.out: $(PY_SRCFILES)
+ rm -f profile.out
$(EPYDOC) -o profile.tmp --name epydoc --css white --debug \
--url http://epydoc.sourceforge.net --profile-epydoc \
--inheritance=listed --navlink "epydoc $(VERSION)"\
--docformat plaintext -v --graph all $(PY_SRC)
- rm -rf profile.tmp
+ rm -rf profile.tmp hotshot.out
##//////////////////////////////////////////////////////////////////////
## Standard Library docs
@@ -221,6 +222,7 @@
SLFILES = $(shell find /usr/lib/$(PYTHON)/ -name '*.py' -o -name '*.so' \
|grep -v "/$(PYTHON)/config/" \
|grep -v "/$(PYTHON)/lib-old/" \
+ |grep -v "/$(PYTHON)/idlelib/" \
|grep -v "/$(PYTHON)/site-packages/" \
|grep -v "/$(PYTHON)/__phello__\.foo\.py" )
PY_PRINT_BUILTINS = "import sys; print ' '.join(sys.builtin_module_names)"
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2006-09-06 23:46:32
|
Revision: 1362
http://svn.sourceforge.net/epydoc/?rev=1362&view=rev
Author: edloper
Date: 2006-09-06 16:46:28 -0700 (Wed, 06 Sep 2006)
Log Message:
-----------
- Whitespace change in output of a test
Modified Paths:
--------------
trunk/epydoc/src/epydoc/test/encoding.doctest
Modified: trunk/epydoc/src/epydoc/test/encoding.doctest
===================================================================
--- trunk/epydoc/src/epydoc/test/encoding.doctest 2006-09-06 23:45:57 UTC (rev 1361)
+++ trunk/epydoc/src/epydoc/test/encoding.doctest 2006-09-06 23:46:28 UTC (rev 1362)
@@ -251,7 +251,6 @@
... @group \xc2\x80: x
... """
... ''')
- <BLANKLINE>
abc ABC 123 € ߿ ࠀ
abc ABC 123 € ߿ ࠀ
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2006-09-06 23:46:00
|
Revision: 1361
http://svn.sourceforge.net/epydoc/?rev=1361&view=rev
Author: edloper
Date: 2006-09-06 16:45:57 -0700 (Wed, 06 Sep 2006)
Log Message:
-----------
- Exception message for type errors in DottedName() params changed
Modified Paths:
--------------
trunk/epydoc/src/epydoc/test/apidoc.doctest
Modified: trunk/epydoc/src/epydoc/test/apidoc.doctest
===================================================================
--- trunk/epydoc/src/epydoc/test/apidoc.doctest 2006-09-06 23:45:27 UTC (rev 1360)
+++ trunk/epydoc/src/epydoc/test/apidoc.doctest 2006-09-06 23:45:57 UTC (rev 1361)
@@ -160,7 +160,7 @@
InvalidDottedName: Bad identifier '1+2'
>>> DottedName({})
Traceback (most recent call last):
- InvalidDottedName: Bad identifier {}
+ TypeError: Bad identifier {}: expected DottedName or str
The one exception is that '??' is treated as if it were a valid python
identifier:
@@ -216,7 +216,7 @@
The constructor does not accept positional arguments; and any keyword
argument that does not correspond to a valid attribute will generate a
-TypeError:
+TypeError (but only if epydoc.DEBUG is true):
>>> APIDoc('foo')
Traceback (most recent call last):
@@ -226,7 +226,7 @@
TypeError: APIDoc got unexpected arg 'foo'
Any assignment to an attribute that's not valid will also generate a
-TypeError:
+TypeError (but only if epydoc.DEBUG is true):
>>> api_doc = APIDoc(docstring='ds')
>>> api_doc.foo = 0
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
