[Epydoc-commits] SF.net SVN: epydoc: [1354] trunk/epydoc/src/epydoc
Brought to you by:
edloper
Menu
▾
▴
[Epydoc-commits] SF.net SVN: epydoc: [1354] trunk/epydoc/src/epydoc
|
From: <ed...@us...> - 2006-09-06 19:08:25
|
Revision: 1354
http://svn.sourceforge.net/epydoc/?rev=1354&view=rev
Author: edloper
Date: 2006-09-06 12:08:13 -0700 (Wed, 06 Sep 2006)
Log Message:
-----------
- Fixed broken crossref links in various docstrings
- Updated module docstrings in docparser & docintrospector
- Removed unused method HTMLWriter._get_index_terms()
- Don't report a failed xref if the identifier in question is
a parameter of the current function.
- If _HTMLDocstringLinker.translate_identifier_xref can't find a
target, then try checking in the contexts of the ancestor
classes (in case the docstring was inherited).
Modified Paths:
--------------
trunk/epydoc/src/epydoc/apidoc.py
trunk/epydoc/src/epydoc/checker.py
trunk/epydoc/src/epydoc/docbuilder.py
trunk/epydoc/src/epydoc/docintrospecter.py
trunk/epydoc/src/epydoc/docparser.py
trunk/epydoc/src/epydoc/docwriter/dotgraph.py
trunk/epydoc/src/epydoc/docwriter/html.py
trunk/epydoc/src/epydoc/docwriter/latex.py
trunk/epydoc/src/epydoc/gui.py
trunk/epydoc/src/epydoc/log.py
Modified: trunk/epydoc/src/epydoc/apidoc.py
===================================================================
--- trunk/epydoc/src/epydoc/apidoc.py 2006-09-06 15:51:15 UTC (rev 1353)
+++ trunk/epydoc/src/epydoc/apidoc.py 2006-09-06 19:08:13 UTC (rev 1354)
@@ -813,8 +813,8 @@
dictionary mapping from identifiers to C{VariableDoc}s. This
dictionary contains all names defined by the namespace,
including imported variables, aliased variables, and variables
- inherited from base classes (once L{DocInheriter
- <epydoc.docinheriter.DocInheriter>} has added them).
+ inherited from base classes (once L{inherit_docs()
+ <epydoc.docbuilder.inherit_docs>} has added them).
@type: C{dict} from C{string} to L{VariableDoc}"""
sorted_variables = UNKNOWN
"""@ivar: A list of all variables defined by this
@@ -1048,8 +1048,8 @@
@require: The L{sorted_variables}, L{variable_groups}, and
L{submodule_groups} attributes must be initialized before
- this method can be used. See L{init_sorted_variables()}
- and L{init_groups()}.
+ this method can be used. See L{init_sorted_variables()},
+ L{init_variable_groups()}, and L{init_submodule_groups()}.
@param value_type: A string specifying the value type for
which variables should be returned. Valid values are:
@@ -1225,7 +1225,7 @@
@require: The L{sorted_variables} and L{variable_groups}
attributes must be initialized before this method can be
used. See L{init_sorted_variables()} and
- L{init_groups()}.
+ L{init_variable_groups()}.
@param value_type: A string specifying the value type for
which variables should be returned. Valid values are:
@@ -1365,7 +1365,7 @@
"""@ivar: A list of names of decorators that were applied to this
routine, in the order that they are listed in the source code.
(I.e., in the reverse of the order that they were applied in.)
- @type: C{list} of L{string}"""
+ @type: C{list} of C{string}"""
#} end of "decorators" group
#{ Information Extracted from Docstrings
@@ -1543,7 +1543,7 @@
"""A mapping from C{profile} function ids to corresponding
C{APIDoc} objects. A function id is a tuple of the form
C{(filename, lineno, funcname)}. This is used to update
- the L{callers} and L{calleeds} variables."""
+ the L{callers} and L{callees} variables."""
self._container_cache = {}
"""A cache for the L{container()} method, to increase speed."""
Modified: trunk/epydoc/src/epydoc/checker.py
===================================================================
--- trunk/epydoc/src/epydoc/checker.py 2006-09-06 15:51:15 UTC (rev 1353)
+++ trunk/epydoc/src/epydoc/checker.py 2006-09-06 19:08:13 UTC (rev 1354)
@@ -53,7 +53,7 @@
- Public/private specifiers indicate whether public or private
objects should be checked: L{PRIVATE}.
- Check specifiers indicate what checks should be run on the
- objects: L{TYPE}; L{DESCR}; L{DESCR_LAZY}; L{AUTHOR};
+ objects: L{TYPE}; L{DESCR}; L{AUTHOR};
and L{VERSION}.
The L{check} method is used to perform a check on the
@@ -66,7 +66,7 @@
values together:
>>> checker.check(DocChecker.MODULE | DocChecker.CLASS |
- ... DocChecker.FUNC | DocChecker.DESCR_LAZY)
+ ... DocChecker.FUNC )
@group Types: MODULE, CLASS, FUNC, VAR, IVAR, CVAR, PARAM,
RETURN, ALL_T
@@ -98,7 +98,7 @@
@cvar ALL_T: Type specifier that indicates that the documentation
of all objects should be checked.
- @group Checks: TYPE, AUTHOR, VERSION, DESCR_LAZY, DESCR, ALL_C
+ @group Checks: TYPE, AUTHOR, VERSION, DESCR, ALL_C
@type TYPE: C{int}
@cvar TYPE: Check specifier that indicates that every variable and
parameter should have a C{@type} field.
@@ -235,7 +235,7 @@
L{_check_class}, and L{_check_func}.
@param doc: The documentation that should be checked.
- @type doc: L{ObjDoc}
+ @type doc: L{APIDoc}
@rtype: C{None}
"""
if ((self._checks & DocChecker.DESCR) and
@@ -287,7 +287,7 @@
whose name is C{name}.
@param doc: The documentation for the variable to check.
- @type doc: L{Doc}
+ @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.
Modified: trunk/epydoc/src/epydoc/docbuilder.py
===================================================================
--- trunk/epydoc/src/epydoc/docbuilder.py 2006-09-06 15:51:15 UTC (rev 1353)
+++ trunk/epydoc/src/epydoc/docbuilder.py 2006-09-06 19:08:13 UTC (rev 1354)
@@ -36,7 +36,7 @@
The main interface to C{epydoc.docbuilder} consists of two functions:
- - L{build_docs()} -- Builds documentation for a single item, and
+ - L{build_doc()} -- Builds documentation for a single item, and
returns it as an L{APIDoc} object.
- L{build_doc_index()} -- Builds documentation for a collection of
items, and returns it as a L{DocIndex} object.
@@ -57,7 +57,7 @@
######################################################################
## Contents
######################################################################
-## 1. build_docs() -- the main interface.
+## 1. build_doc() & build_doc_index() -- the main interface.
## 2. merge_docs() -- helper, used to merge parse & introspect info
## 3. link_imports() -- helper, used to connect imported vars w/ values
## 4. assign_canonical_names() -- helper, used to set canonical names
@@ -77,7 +77,7 @@
from epydoc.compat import * # Backwards compatibility
######################################################################
-## 1. build_docs()
+## 1. build_doc()
######################################################################
def build_doc(item, introspect=True, parse=True, add_submodules=True):
Modified: trunk/epydoc/src/epydoc/docintrospecter.py
===================================================================
--- trunk/epydoc/src/epydoc/docintrospecter.py 2006-09-06 15:51:15 UTC (rev 1353)
+++ trunk/epydoc/src/epydoc/docintrospecter.py 2006-09-06 19:08:13 UTC (rev 1354)
@@ -10,12 +10,14 @@
Extract API documentation about python objects by directly introspecting
their values.
-L{DocIntrospecter} is a processing class that examines Python objects via
-introspection, and uses the information it finds to create L{APIDoc}
-objects containing the API documentation for those objects.
+The function L{introspect_docs()}, which provides the main interface
+of this module, examines a Python objects via introspection, and uses
+the information it finds to create an L{APIDoc} objects containing the
+API documentation for that objects.
-C{DocIntrospecter} can be subclassed to extend the set of object types
-that it supports.
+The L{register_introspecter()} method can be used to extend the
+functionality of C{docintrospector}, by providing methods that handle
+special value types.
"""
__docformat__ = 'epytext en'
@@ -61,41 +63,6 @@
## Introspection
######################################################################
-# [xx] old:
-"""
-An API documentation extractor based on introspecting python values.
-C{DocIntrospecter} examines Python objects via introspection, and uses
-the information it finds to create L{APIDoc} objects containing
-the API documentation for those objects. The main interface to
-the C{DocIntrospecter} class is the L{introspect} method, which takes a
-Python value, and returns an L{APIDoc} that describes it.
-
-Currently, C{DocIntrospecter} can extract documentation information
-from the following object types:
-
- - modules
- - classes
- - functions
- - methods
- - class methods
- - static methods
- - builtin routines
- - properties
-
-Subclassing
-===========
-C{DocIntrospecter} can be subclassed, to extend the set of object
-types that it supports. C{DocIntrospecter} can be extended in
-several different ways:
-
- - A subclass can override one of the existing introspection methods
- to modify the behavior for a currently supported object type.
-
- - A subclass can add support for a new type by adding a new
- introspection method; and extending L{introspecter_method()} to
- return that method for values of the new type.
-"""
-
def introspect_docs(value=None, name=None, filename=None, context=None,
is_script=False):
"""
Modified: trunk/epydoc/src/epydoc/docparser.py
===================================================================
--- trunk/epydoc/src/epydoc/docparser.py 2006-09-06 15:51:15 UTC (rev 1353)
+++ trunk/epydoc/src/epydoc/docparser.py 2006-09-06 19:08:13 UTC (rev 1354)
@@ -10,13 +10,42 @@
Extract API documentation about python objects by parsing their source
code.
-L{DocParser} is a processing class that reads the Python source code
-for one or more modules, and uses it to create L{APIDoc} objects
-containing the API documentation for the variables and values defined
-in those modules.
+The function L{parse_docs()}, which provides the main interface
+of this module, reads and parses the Python source code for a
+module, and uses it to create an L{APIDoc} object containing
+the API documentation for the variables and values defined in
+that modules.
-C{DocParser} can be subclassed to extend the set of source code
-constructions that it supports.
+Currently, C{parse_docs()} extracts documentation from the following
+source code constructions:
+
+ - module docstring
+ - import statements
+ - class definition blocks
+ - function definition blocks
+ - assignment statements
+ - simple assignment statements
+ - assignment statements with multiple C{'='}s
+ - assignment statements with unpacked left-hand sides
+ - assignment statements that wrap a function in classmethod
+ or staticmethod.
+ - assignment to special variables __path__, __all__, and
+ __docformat__.
+ - delete statements
+
+C{parse_docs()} does not yet support the following source code
+constructions:
+
+ - assignment statements that create properties
+
+By default, C{parse_docs()} will expore the contents of top-level
+C{try} and C{if} blocks. If desired, C{parse_docs()} can also
+be configured to explore the contents of C{while} and C{for} blocks.
+(See the configuration constants, below.)
+
+@todo: Make it possible to extend the functionality of C{parse_docs()},
+ by replacing process_line with a dispatch table that can be
+ customized (similarly to C{docintrospector.register_introspector()}).
"""
__docformat__ = 'epytext en'
@@ -59,52 +88,6 @@
C{ValueDoc} objects.
@type: C{dict}"""
-# [xx] outdated:
-"""
-An API documentation extractor based on source code parsing.
-C{DocParser} reads and parses the Python source code for one or
-more modules, and uses it to create L{APIDoc} objects containing
-the API documentation for the variables and values defined in
-those modules. The main interface method is L{parse()}, which
-returns the documentation for an object with a given dotted name,
-or a module with a given filename.
-
-Currently, C{DocParser} extracts documentation from the following
-source code constructions:
-
- - module docstring
- - import statements
- - class definition blocks
- - function definition blocks
- - assignment statements
- - simple assignment statements
- - assignment statements with multiple C{'='}s
- - assignment statements with unpacked left-hand sides
- - assignment statements that wrap a function in classmethod
- or staticmethod.
- - assignment to special variables __path__, __all__, and
- __docformat__.
- - delete statements
-
-C{DocParser} does not yet support the following source code
-constructions:
-
- - assignment statements that create properties
-
-By default, C{DocParser} will expore the contents of top-level
-C{try} and C{if} blocks. If desired, C{DocParser} can also
-be told to explore the contents of C{while} and C{for} blocks.
-
-Subclassing
-===========
-C{DocParser} can be subclassed, to extend the set of source code
-constructions that it supports. C{DocParser} can be extended in
-several different ways:
-
- - [XX] fill this in!
-
-"""
-
#////////////////////////////////////////////////////////////
# Configuration Constants
#////////////////////////////////////////////////////////////
@@ -211,7 +194,7 @@
C{ModuleDoc} describing its contents.
@param name: The fully-qualified python dotted name of any
value (including packages, modules, classes, and
- functions). C{DocParser} will automatically figure out
+ functions). C{parse_docs()} will automatically figure out
which module(s) it needs to parse in order to find the
documentation for the specified object.
@param context: The API documentation for the package that
Modified: trunk/epydoc/src/epydoc/docwriter/dotgraph.py
===================================================================
--- trunk/epydoc/src/epydoc/docwriter/dotgraph.py 2006-09-06 15:51:15 UTC (rev 1353)
+++ trunk/epydoc/src/epydoc/docwriter/dotgraph.py 2006-09-06 19:08:13 UTC (rev 1354)
@@ -45,7 +45,7 @@
class DotGraph:
"""
- A `dot` directed graph. The contents of the graph are
+ A ``dot`` directed graph. The contents of the graph are
constructed from the following instance variables:
- `nodes`: A list of `DotGraphNode`\\s, encoding the nodes
@@ -62,7 +62,7 @@
The `link()` method can be used to resolve crossreference links
within the graph. In particular, if the 'href' attribute of any
- node or edge is assigned a value of the form `<name>`, then it
+ node or edge is assigned a value of the form ``<name>``, then it
will be replaced by the URL of the object with that name. This
applies to the `body` as well as the `nodes` and `edges`.
@@ -190,8 +190,8 @@
def link(self, docstring_linker):
"""
- Replace any href attributes whose value is <name> with
- the url of the object whose name is <name>.
+ Replace any href attributes whose value is ``<name>`` with
+ the url of the object whose name is ``<name>``.
"""
# Link xrefs in nodes
self._link_href(self.node_defaults, docstring_linker)
@@ -237,7 +237,7 @@
def render(self, language='gif'):
"""
Use the ``dot`` command to render this graph, using the output
- format `language`. Return the result as a string, or `None`
+ format `language`. Return the result as a string, or ``None``
if the rendering failed.
"""
return self._run_dot('-T%s' % language)
@@ -394,7 +394,7 @@
`class_doc`.
:Parameters:
- `linker` : `DocstringLinker<markup.DocstringLinker>`
+ `linker` : `markup.DocstringLinker`
Used to look up URLs for classes.
`context` : `APIDoc`
The context in which this node will be drawn; dotted
@@ -526,7 +526,7 @@
labelled with the variable name, and marked with '0..1' at
the type end of the edge.
- The edges created by `link_attribute()` are handled internally
+ The edges created by `link_attributes()` are handled internally
by `DotGraphUmlClassNode`; they should *not* be added directly
to the `DotGraph`.
@@ -594,7 +594,7 @@
def _add_attribute_edge(self, var, nodes, type_str, **attribs):
"""
- Helper for `link_attribute()`: try to add an edge for the
+ Helper for `link_attributes()`: try to add an edge for the
given attribute variable `var`. Return ``True`` if
successful.
"""
@@ -1156,12 +1156,12 @@
def call_graph(api_docs, docindex, linker, context=None, **options):
"""
:param options:
- - `dir`: rankdir for the graph. (default=LR)
- - `add_callers`: also include callers for any of the
- routines in `api_docs`. (default=False)
- - `add_callees`: also include callees for any of the
- routines in `api_docs`. (default=False)
- :todo: Add an `exclude` option?
+ - ``dir``: rankdir for the graph. (default=LR)
+ - ``add_callers``: also include callers for any of the
+ routines in ``api_docs``. (default=False)
+ - ``add_callees``: also include callees for any of the
+ routines in ``api_docs``. (default=False)
+ :todo: Add an ``exclude`` option?
"""
if docindex.callers is None:
log.warning("No profiling information for call graph!")
Modified: trunk/epydoc/src/epydoc/docwriter/html.py
===================================================================
--- trunk/epydoc/src/epydoc/docwriter/html.py 2006-09-06 15:51:15 UTC (rev 1353)
+++ trunk/epydoc/src/epydoc/docwriter/html.py 2006-09-06 19:08:13 UTC (rev 1354)
@@ -2488,7 +2488,7 @@
def contextual_label(self, doc, context):
"""
- Return the label for L{doc} to be shown in C{context}.
+ Return the label for C{doc} to be shown in C{context}.
"""
if doc.canonical_name is None:
if doc.parse_repr is not None:
@@ -2819,23 +2819,6 @@
index.setdefault(arg, []).append( (doc, descr_list) )
return index
- def _get_index_terms(self, parsed_docstring, link, terms, links):
- """
- A helper function for L{_extract_term_index}.
-
- For each index term M{t} with key M{k} in C{parsed_docstring},
- modify C{terms} and C{links} as follows:
- - Set C{terms[M{k}] = t} (if C{terms[M{k}]} doesn't exist).
- - Append C{link} to C{links[M{k}]}.
- """
- if parsed_docstring in (None, UNKNOWN): return
- for term in parsed_docstring.index_terms():
- key = self._term_index_to_anchor(term)
- if not terms.has_key(key):
- terms[key] = term
- links[key] = []
- links[key].append(link)
-
def _term_index_to_anchor(self, term):
"""
Given the name of an inline index item, construct a URI anchor.
@@ -3169,6 +3152,16 @@
# Find the APIDoc for it (if it's available).
doc = self.docindex.find(identifier, self.container)
+ # If we didn't find a target, then try checking in the contexts
+ # of the ancestor classes.
+ if doc is None and isinstance(self.container, RoutineDoc):
+ container = self.docindex.get_vardoc(
+ self.container.canonical_name)
+ while (doc is None and container not in (None, UNKNOWN)
+ and container.overrides not in (None, UNKNOWN)):
+ container = container.overrides
+ doc = self.docindex.find(identifier, container)
+
# Translate it into HTML.
if doc is None:
self._failed_xref(identifier)
@@ -3196,6 +3189,12 @@
def _failed_xref(self, identifier):
"""Add an identifier to the htmlwriter's failed crossreference
list."""
+ # Don't count it as a failed xref if it's a parameter of the
+ # current function.
+ if (isinstance(self.container, RoutineDoc) and
+ identifier in self.container.all_args()):
+ return
+
failed_xrefs = self.htmlwriter._failed_xrefs
context = self.container.canonical_name
failed_xrefs.setdefault(identifier,{})[context] = 1
Modified: trunk/epydoc/src/epydoc/docwriter/latex.py
===================================================================
--- trunk/epydoc/src/epydoc/docwriter/latex.py 2006-09-06 15:51:15 UTC (rev 1353)
+++ trunk/epydoc/src/epydoc/docwriter/latex.py 2006-09-06 19:08:13 UTC (rev 1354)
@@ -428,7 +428,7 @@
def write_module_tree_item(self, out, doc, depth=0):
"""
- Helper function for L{_module_tree} and L{_module_list}.
+ Helper function for L{write_module_tree} and L{write_module_list}.
@rtype: C{string}
"""
Modified: trunk/epydoc/src/epydoc/gui.py
===================================================================
--- trunk/epydoc/src/epydoc/gui.py 2006-09-06 15:51:15 UTC (rev 1353)
+++ trunk/epydoc/src/epydoc/gui.py 2006-09-06 19:08:13 UTC (rev 1354)
@@ -208,7 +208,7 @@
@param options: The options to use for generating documentation.
This includes keyword options that can be given to
- L{html.HTMLFormatter}, as well as the option C{target}, which
+ L{docwriter.html.HTMLWriter}, as well as the option C{target}, which
controls where the output is written to.
@type options: C{dictionary}
"""
Modified: trunk/epydoc/src/epydoc/log.py
===================================================================
--- trunk/epydoc/src/epydoc/log.py 2006-09-06 15:51:15 UTC (rev 1353)
+++ trunk/epydoc/src/epydoc/log.py 2006-09-06 19:08:13 UTC (rev 1354)
@@ -70,13 +70,13 @@
def start_block(self, header):
"""
- Start a new message block. Any calls to L{info}, L{warn}, or
- L{error} that occur between a call to C{start_block} and a
- corresponding call to C{end_block} will be grouped together,
- and displayed with a common header. C{start_block} can be
- called multiple times (to form nested blocks), but every call
- to C{start_block} I{must} be balanced by a call to
- C{end_block}.
+ Start a new message block. Any calls to L{info()},
+ L{warning()}, or L{error()} that occur between a call to
+ C{start_block} and a corresponding call to C{end_block} will
+ be grouped together, and displayed with a common header.
+ C{start_block} can be called multiple times (to form nested
+ blocks), but every call to C{start_block} I{must} be balanced
+ by a call to C{end_block}.
"""
def end_block(self):
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
