epydoc-commits Mailing List for Python API documentation generation tool (Page 21)
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: <ed...@us...> - 2006-08-23 16:17:24
|
Revision: 1310 Author: edloper Date: 2006-08-23 09:17:18 -0700 (Wed, 23 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1310&view=rev Log Message: ----------- - changed is_module_file() and is_package_dir() to return false when given a non-string object (rather than raising an exception) Modified Paths: -------------- trunk/epydoc/src/epydoc/util.py Modified: trunk/epydoc/src/epydoc/util.py =================================================================== --- trunk/epydoc/src/epydoc/util.py 2006-08-23 15:58:06 UTC (rev 1309) +++ trunk/epydoc/src/epydoc/util.py 2006-08-23 16:17:18 UTC (rev 1310) @@ -26,6 +26,9 @@ PY_BIN_EXTENSIONS = ['.pyc', '.so', '.pyd'] def is_module_file(path): + # Make sure it's a file name. + if not isinstance(path, basestring): + return False (dir, filename) = os.path.split(path) (basename, extension) = os.path.splitext(filename) return (os.path.isfile(path) and @@ -42,7 +45,9 @@ (i.e., it names a directory that contsains a valid __init__ file, and its name is a valid identifier). """ - # Make sure it's a directory. + # Make sure it's a directory name. + if not isinstance(dirname, basestring): + return False if not os.path.isdir(dirname): return False dirname = os.path.abspath(dirname) This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-23 15:58:14
|
Revision: 1309 Author: edloper Date: 2006-08-23 08:58:06 -0700 (Wed, 23 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1309&view=rev Log Message: ----------- - Only import pstats/profile when we need them, and if the import fails, then issue an error message, rather than crashing. (pstats is not installed by default on some systems.) Modified Paths: -------------- trunk/epydoc/src/epydoc/cli.py Modified: trunk/epydoc/src/epydoc/cli.py =================================================================== --- trunk/epydoc/src/epydoc/cli.py 2006-08-23 15:47:09 UTC (rev 1308) +++ trunk/epydoc/src/epydoc/cli.py 2006-08-23 15:58:06 UTC (rev 1309) @@ -63,7 +63,7 @@ """ __docformat__ = 'epytext en' -import sys, os, time, re, pstats, pickle +import sys, os, time, re, pickle from glob import glob from optparse import OptionParser, OptionGroup import epydoc @@ -470,6 +470,9 @@ # Load profile information, if it was given. if options.pstat_files: + try: import pstats + except ImportError: + log.error("Could not import pstats -- ignoring pstat files.") try: profile_stats = pstats.Stats(options.pstat_files[0]) for filename in options.pstat_files[1:]: @@ -672,7 +675,10 @@ print >>sys.stderr, 'Use --debug to see trace information.' def _profile(): - import profile, pstats + try: import profile + except ImportError: + print >>sys.stderr, "Could not import profile module!" + return try: prof = profile.Profile() prof = prof.runctx('main(*parse_arguments())', globals(), {}) @@ -680,9 +686,13 @@ pass prof.dump_stats('profile.out') return + # Use the pstats statistical browser. This is made unnecessarily # difficult because the whole browser is wrapped in an # if __name__=='__main__' clause. + try: import pstats + except ImportError: + log.error("Could not import pstats -- skipping browser") try: pstats_pyfile = os.path.splitext(pstats.__file__)[0]+'.py' sys.argv = ['pstats.py', 'profile.out'] This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-23 15:47:15
|
Revision: 1308 Author: edloper Date: 2006-08-23 08:47:09 -0700 (Wed, 23 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1308&view=rev Log Message: ----------- - Changed DocIndex.find() to return the VariableDoc instead of the ValueDoc for variables with GenericValueDoc values. Modified Paths: -------------- trunk/epydoc/src/epydoc/apidoc.py Modified: trunk/epydoc/src/epydoc/apidoc.py =================================================================== --- trunk/epydoc/src/epydoc/apidoc.py 2006-08-23 15:38:56 UTC (rev 1307) +++ trunk/epydoc/src/epydoc/apidoc.py 2006-08-23 15:47:09 UTC (rev 1308) @@ -29,6 +29,8 @@ because several variables can contain the same value: each variable should be described by a separate C{VariableDoc}; but we only need one C{ValueDoc}, since they share a single value. + +@todo: Add a cache to canonical name lookup? """ __docformat__ = 'epytext en' @@ -1621,8 +1623,8 @@ def find(self, name, context): """ - Look for a C{ValueDoc} named C{name}, relative to C{context}. - Return the C{ValueDoc} if one is found; otherwise, return + Look for an C{APIDoc} named C{name}, relative to C{context}. + Return the C{APIDoc} if one is found; otherwise, return C{None}. C{find} looks in the following places, in order: - Function parameters (if one matches, return C{None}) - All enclosing namespaces, from closest to furthest. @@ -1632,7 +1634,7 @@ - Parameter attributes @type name: C{str} or L{DottedName} - @type context: L{ValueDoc} + @type context: L{APIDoc} """ if isinstance(name, basestring): name = re.sub(r'\(.*\)$', '', name.strip()) @@ -1653,8 +1655,11 @@ for i in range(len(container_name), -1, -1): relative_name = container_name[:i]+name # Is `name` the absolute name of a documented value? + # (excepting GenericValueDoc values.) val_doc = self.get_valdoc(relative_name) - if val_doc is not None: return val_doc + if (val_doc is not None and + not isinstance(val_doc, GenericValueDoc)): + return val_doc # Is `name` the absolute name of a documented variable? var_doc = self.get_vardoc(relative_name) if var_doc is not None: return var_doc This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-23 15:39:01
|
Revision: 1307 Author: edloper Date: 2006-08-23 08:38:56 -0700 (Wed, 23 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1307&view=rev Log Message: ----------- - Fixed 'failed identifier crossreference' detection. 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-08-23 15:29:41 UTC (rev 1306) +++ trunk/epydoc/src/epydoc/docwriter/html.py 2006-08-23 15:38:56 UTC (rev 1307) @@ -9,6 +9,8 @@ """ The HTML output generator for epydoc. The main interface provided by this module is the L{HTMLWriter} class. + +@todo: Add a cache to L{HTMLWriter.url()}? """ __docformat__ = 'epytext en' @@ -696,7 +698,7 @@ #//////////////////////////////////////////////////////////// def write_sourcecode(self, out, doc, name_to_docs): - t0 = time.time() + #t0 = time.time() filename = doc.filename name = str(doc.canonical_name) @@ -3113,22 +3115,20 @@ # Translate it into HTML. if doc is None: + self._failed_xref(identifier) return '<code class="link">%s</code>' % label else: return self.htmlwriter.href(doc, label, 'link') # [xx] Should this be added to the DocstringLinker interface??? + # Currently, this is *only* used by dotgraph. def url_for(self, identifier): if isinstance(identifier, (basestring, DottedName)): doc = self.docindex.find(identifier, self.container) if doc: return self.htmlwriter.url(doc) else: - # [xx] ignore if it's inside an import?? - # Record that we failed to find it. - failed_xrefs = self.htmlwriter._failed_xrefs - context = self.container.canonical_name - failed_xrefs.setdefault(identifier,{})[context] = 1 + return None elif isinstance(identifier, APIDoc): return self.htmlwriter.url(identifier) @@ -3137,3 +3137,9 @@ else: raise TypeError('Expected string or APIDoc') + def _failed_xref(self, identifier): + """Add an identifier to the htmlwriter's failed crossreference + list.""" + failed_xrefs = self.htmlwriter._failed_xrefs + context = self.container.canonical_name + failed_xrefs.setdefault(identifier,{})[context] = 1 This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-23 15:29:45
|
Revision: 1306 Author: edloper Date: 2006-08-23 08:29:41 -0700 (Wed, 23 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1306&view=rev Log Message: ----------- - Fixed typo in title Modified Paths: -------------- trunk/epydoc/doc/whatsnew.html Modified: trunk/epydoc/doc/whatsnew.html =================================================================== --- trunk/epydoc/doc/whatsnew.html 2006-08-23 15:06:25 UTC (rev 1305) +++ trunk/epydoc/doc/whatsnew.html 2006-08-23 15:29:41 UTC (rev 1306) @@ -1,6 +1,6 @@ <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <html> <head> -<title>Epydoc: Frequently Asked Questions</title> +<title>Epydoc: What's New</title> <link rel="stylesheet" href="epydoc.css" type="text/css"/> </head> <!-- $Id: faq.html 602 2003-09-07 23:49:56Z edloper $ --> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-23 15:06:30
|
Revision: 1305 Author: edloper Date: 2006-08-23 08:06:25 -0700 (Wed, 23 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1305&view=rev Log Message: ----------- - Docstring fix for HTMLWriter - Check if pyval_repr is available, even if pyval is UNKNOWN. This is used if we're writing html for docs came from a pickle. 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-08-23 15:01:24 UTC (rev 1304) +++ trunk/epydoc/src/epydoc/docwriter/html.py 2006-08-23 15:06:25 UTC (rev 1305) @@ -282,8 +282,8 @@ end of their group; if C{inheritance='included'}, then inherited objects are mixed in with non-inherited objects. The default is 'grouped'. - @type include_sourcecode: C{boolean} - @param include_sourcecode: If true, then generate colorized + @type include_source_code: C{boolean} + @param include_sourc_ecode: If true, then generate colorized source code files for each python module. """ self.docindex = docindex @@ -696,6 +696,8 @@ #//////////////////////////////////////////////////////////// def write_sourcecode(self, out, doc, name_to_docs): + t0 = time.time() + filename = doc.filename name = str(doc.canonical_name) @@ -715,6 +717,9 @@ # Footer self.write_navbar(out, doc) self.write_footer(out) + + #log.debug('[%6.2f sec] Wrote pysrc for %s' % + # (time.time()-t0, name)) #//////////////////////////////////////////////////////////// #{ 2.2. Class Pages @@ -2239,6 +2244,8 @@ if val_doc is UNKNOWN: return '' if val_doc.pyval is not UNKNOWN: return self.pprint_pyval(val_doc.pyval) + elif val_doc.pyval_repr() is not UNKNOWN: + s = plaintext_to_html(val_doc.pyval_repr()) elif val_doc.parse_repr is not UNKNOWN: s = plaintext_to_html(val_doc.parse_repr) else: This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-23 15:02:19
|
Revision: 1304 Author: edloper Date: 2006-08-23 08:01:24 -0700 (Wed, 23 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1304&view=rev Log Message: ----------- - Turned off GUESS_LINK_TARGETS flag in source code colorizer. - Optimized code that guesses link targets, to make it run faster. (Based on a patch provided by Daniel von Dincklage.) Modified Paths: -------------- trunk/epydoc/src/epydoc/docwriter/html_colorize.py Modified: trunk/epydoc/src/epydoc/docwriter/html_colorize.py =================================================================== --- trunk/epydoc/src/epydoc/docwriter/html_colorize.py 2006-08-23 14:59:28 UTC (rev 1303) +++ trunk/epydoc/src/epydoc/docwriter/html_colorize.py 2006-08-23 15:01:24 UTC (rev 1304) @@ -598,7 +598,7 @@ #: If true, then try to guess which target is appropriate for #: linked names; if false, then always open a div asking the #: user which one they want. - GUESS_LINK_TARGETS = True + GUESS_LINK_TARGETS = False def __init__(self, module_filename, module_name, docindex=None, url_func=None, name_to_docs=None): @@ -938,15 +938,18 @@ if (self.GUESS_LINK_TARGETS and self.docindex is not None and self.url_func is not None): context = [n for n in self.context if n is not None] - container = DottedName(self.module_name, *context) - doc = self.docindex.get_vardoc(container+toktext) - if doc is not None: - url = self.url_func(doc) + container = self.docindex.get_vardoc( + DottedName(self.module_name, *context)) + if isinstance(container, NamespaceDoc): + doc = container.variables.get(toktext) + if doc is not None: + url = self.url_func(doc) + tooltip = str(doc.canonical_name) # Otherwise, check the name_to_docs index to see what # else this name might refer to. if (url is None and self.name_to_docs is not None and self.url_func is not None): - docs = self.name_to_docs.get(toktext, []) + docs = self.name_to_docs.get(toktext) if docs: tooltip='\n'.join([str(d.canonical_name) for d in docs]) This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-23 15:00:20
|
Revision: 1303 Author: edloper Date: 2006-08-23 07:59:28 -0700 (Wed, 23 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1303&view=rev Log Message: ----------- - Added support for pickling & unpickling docs. Modified Paths: -------------- trunk/epydoc/src/epydoc/cli.py Modified: trunk/epydoc/src/epydoc/cli.py =================================================================== --- trunk/epydoc/src/epydoc/cli.py 2006-08-23 14:58:34 UTC (rev 1302) +++ trunk/epydoc/src/epydoc/cli.py 2006-08-23 14:59:28 UTC (rev 1303) @@ -63,7 +63,7 @@ """ __docformat__ = 'epytext en' -import sys, os, time, re, pstats +import sys, os, time, re, pstats, pickle from glob import glob from optparse import OptionParser, OptionGroup import epydoc @@ -112,6 +112,9 @@ action_group.add_option( # --check "--check", action="store_const", dest="action", const="check", help="Check completeness of docs.") + action_group.add_option( + "--pickle", action="store_const", dest="action", const="pickle", + help="Write the documentation to a pickle file.") # Add options -- Options options_group.add_option( # --output @@ -229,7 +232,7 @@ docformat=DEFAULT_DOCFORMAT, show_private=True, show_imports=False, inheritance="listed", - verbose=0, quiet=0, + verbose=0, quiet=0, load_pickle=False, parse=True, introspect=True, debug=epydoc.DEBUG, profile=False, graphs=[], list_classes_separately=False, @@ -249,6 +252,14 @@ else: cf_name = 'config files %s' % ', '.join(options.configfiles) optparser.error('Error reading %s:\n %s' % (cf_name, e)) + + # Check if the input file is a pickle file. + for name in names: + if name.endswith('.pickle'): + if len(names) != 1: + optparse.error("When a pickle file is specified, no other " + "input files may be specified.") + options.load_pickle = True # Check to make sure all options are valid. if len(names) == 0: @@ -403,6 +414,8 @@ 30, # Parsing Docstrings 1, # Inheriting documentation 2] # Sorting & Grouping + if options.load_pickle: + stages = [30] # Loading pickled documentation if options.action == 'html': stages += [100] elif options.action == 'text': stages += [30] elif options.action == 'latex': stages += [60] @@ -410,6 +423,7 @@ elif options.action == 'ps': stages += [60,40] elif options.action == 'pdf': stages += [60,50] elif options.action == 'check': stages += [10] + elif options.action == 'pickle': stages += [10] else: raise ValueError, '%r not supported' % options.action if options.parse and not options.introspect: del stages[1] # no merging @@ -419,7 +433,7 @@ log.register_logger(logger) # check the output directory. - if options.action != 'text': + if options.action not in ('text', 'check', 'pickle'): if os.path.exists(options.target): if not os.path.isdir(options.target): return log.error("%s is not a directory" % options.target) @@ -433,10 +447,23 @@ from epydoc.docwriter import dotgraph dotgraph.DOT_PATH = options.dotpath - # Build docs for the named values. - from epydoc.docbuilder import build_doc_index - docindex = build_doc_index(names, options.introspect, options.parse, - add_submodules=(options.action!='text')) + # If the input name is a pickle file, then read the docindex that + # it contains. Otherwise, build the docs for the input names. + if options.load_pickle: + assert len(names) == 1 + log.start_progress('Deserializing') + log.progress(0.1, 'Loading %r' % names[0]) + t0 = time.time() + unpickler = pickle.Unpickler(open(names[0], 'rb')) + unpickler.persistent_load = pickle_persistent_load + docindex = unpickler.load() + log.debug('deserialization time: %.1f sec' % (time.time()-t0)) + log.end_progress() + else: + # Build docs for the named values. + from epydoc.docbuilder import build_doc_index + docindex = build_doc_index(names, options.introspect, options.parse, + add_submodules=(options.action!='text')) if docindex is None: return # docbuilder already logged an error. @@ -463,6 +490,8 @@ write_text(docindex, options) elif options.action == 'check': check_docs(docindex, options) + elif options.action == 'pickle': + write_pickle(docindex, options) else: print >>sys.stderr, '\nUnsupported action %s!' % options.action @@ -490,6 +519,37 @@ html_writer.write(options.target) log.end_progress() +def write_pickle(docindex, options): + """Helper for writing output to a pickle file, which can then be + read in at a later time. But loading the pickle is only marginally + faster than building the docs from scratch, so this has pretty + limited application.""" + if options.target == 'pickle': + options.target = 'api.pickle' + elif not options.target.endswith('.pickle'): + options.target += '.pickle' + + log.start_progress('Serializing output') + log.progress(0.2, 'Writing %r' % options.target) + outfile = open(options.target, 'wb') + pickler = pickle.Pickler(outfile, protocol=0) + pickler.persistent_id = pickle_persistent_id + pickler.dump(docindex) + outfile.close() + log.end_progress() + +def pickle_persistent_id(obj): + """Helper for pickling, which allows us to save and restore UNKNOWN, + which is required to be identical to apidoc.UNKNOWN.""" + if obj is UNKNOWN: return 'UNKNOWN' + else: return None + +def pickle_persistent_load(identifier): + """Helper for pickling, which allows us to save and restore UNKNOWN, + which is required to be identical to apidoc.UNKNOWN.""" + if identifier == 'UNKNOWN': return UNKNOWN + else: raise pickle.UnpicklingError, 'Invalid persistent id' + _RERUN_LATEX_RE = re.compile(r'(?im)^LaTeX\s+Warning:\s+Label\(s\)\s+may' r'\s+have\s+changed.\s+Rerun') This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-23 14:58:37
|
Revision: 1302 Author: edloper Date: 2006-08-23 07:58:34 -0700 (Wed, 23 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1302&view=rev Log Message: ----------- - Added __setstate__/__getstate__ to ValueDoc, to make them pickle-able. - Added caches for DocIndex.container() and DocIndex.get() functions. (Based on a patch provided by Daniel von Dincklage.) Modified Paths: -------------- trunk/epydoc/src/epydoc/apidoc.py Modified: trunk/epydoc/src/epydoc/apidoc.py =================================================================== --- trunk/epydoc/src/epydoc/apidoc.py 2006-08-23 07:03:09 UTC (rev 1301) +++ trunk/epydoc/src/epydoc/apidoc.py 2006-08-23 14:58:34 UTC (rev 1302) @@ -36,7 +36,7 @@ ## Imports ###################################################################### -import types, re, os.path +import types, re, os.path, pickle from epydoc import log import epydoc import __builtin__ @@ -735,9 +735,31 @@ return '<%s %s>' % (self.__class__.__name__, self.pyval_repr()) elif self.parse_repr is not UNKNOWN: return '<%s %s>' % (self.__class__.__name__, self.parse_repr) - else: + else: return '<%s>' % self.__class__.__name__ + def __setstate__(self, state): + self.__dict__ = state + + def __getstate__(self): + """ + State serializer for the pickle module. This is necessary + because sometimes the C{pyval} attribute contains an + un-pickleable value. + """ + # Construct our pickled dictionary. Maintain this dictionary + # as a private attribute, so we can reuse it later, since + # merged objects need to share a single dictionary. + if not hasattr(self, '_ValueDoc__pickle_state'): + self.__pickle_state = self.__dict__.copy() + self.__pickle_state['pyval'] = UNKNOWN + self.__pickle_state['_ValueDoc__pyval_repr'] = self.pyval_repr() + + if not isinstance(self, GenericValueDoc): + assert self.__pickle_state != {} + # Return the pickle state. + return self.__pickle_state + def pyval_repr(self): """ Return a string representation of this value based on its pyval; @@ -745,6 +767,8 @@ be replaced by more of a safe-repr variant. """ if self.pyval is UNKNOWN: + if hasattr(self, '_ValueDoc__pyval_repr'): + return self.__pyval_repr # used after unpickling. return UNKNOWN try: s = '%r' % (self.pyval,) @@ -1502,7 +1526,18 @@ @type: C{list} of L{RoutineDoc}""" self._funcid_to_doc = {} + """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.""" + self._container_cache = {} + """A cache for the L{container()} method, to increase speed.""" + + self._get_cache = {} + """A cache for the L{get_vardoc()} and L{get_valdoc()} methods, + to increase speed.""" + #//////////////////////////////////////////////////////////// # Lookup methods #//////////////////////////////////////////////////////////// @@ -1535,8 +1570,13 @@ and L{get_valdoc()}. """ # Convert name to a DottedName, if necessary. - name = DottedName(name) + if not isinstance(name, DottedName): + name = DottedName(name) + # Check if the result is cached. + val = self._get_cache.get(name) + if val is not None: return val + # Look for an element in the root set whose name is a prefix # of `name`. If we can't find one, then return None. for root_valdoc in self.root: @@ -1551,9 +1591,11 @@ else: # If we found it, then return. if var_doc is not None or val_doc is not None: + self._get_cache[name] = (var_doc, val_doc) return var_doc, val_doc # We didn't find it. + self._get_cache[name] = (None, None) return None, None def _get_from(self, val_doc, identifier): @@ -1655,17 +1697,26 @@ Return the C{ValueDoc} that contains the given C{APIDoc}, or C{None} if its container is not in the index. """ + # Check if the result is cached. + val = self._container_cache.get(api_doc) + if val is not None: return val + if isinstance(api_doc, GenericValueDoc): + self._container_cache[api_doc] = None return None # [xx] unknown. if isinstance(api_doc, VariableDoc): + self._container_cache[api_doc] = api_doc.container return api_doc.container if len(api_doc.canonical_name) == 1: + self._container_cache[api_doc] = None return None elif isinstance(api_doc, ModuleDoc) and api_doc.package is not UNKNOWN: + self._container_cache[api_doc] = api_doc.package return api_doc.package else: - parent = api_doc.canonical_name.container() - return self.get_valdoc(parent) + parent = self.get_valdoc(api_doc.canonical_name.container()) + self._container_cache[api_doc] = parent + return parent #//////////////////////////////////////////////////////////// # Profiling information This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-23 07:03:41
|
Revision: 1301 Author: edloper Date: 2006-08-23 00:03:09 -0700 (Wed, 23 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1301&view=rev Log Message: ----------- - Made ParsedRstDocstring's pickle-able. 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-08-23 05:25:13 UTC (rev 1300) +++ trunk/epydoc/src/epydoc/markup/restructuredtext.py 2006-08-23 07:03:09 UTC (rev 1301) @@ -80,6 +80,8 @@ from docutils.parsers.rst import directives import docutils.nodes import docutils.transforms.frontmatter +import docutils.transforms +import docutils.utils from epydoc.compat import * # Backwards compatibility from epydoc.markup import * @@ -145,6 +147,12 @@ @type document: L{docutils.nodes.document} """ self._document = document + + # The default document reporter and transformer are not + # pickle-able; so replace them with stubs that are. + document.reporter = docutils.utils.Reporter( + document.reporter.source, 'SEVERE', 'SEVERE', '') + document.transformer = docutils.transforms.Transformer(document) def split_fields(self, errors=None): # Inherit docs This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-23 05:25:20
|
Revision: 1300 Author: edloper Date: 2006-08-22 22:25:13 -0700 (Tue, 22 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1300&view=rev Log Message: ----------- - Modified html_colorize.PythonSourceColorizer constructor to take a name_to_docs dictionary as an argument, rather than recomputing it each time. The name_to_docs dictionary is computed by HTMLWriter, and pre-sorted. This optimization should make source colorization faster. Based on a patch provided by Daniel von Dincklage. - In PythonSourceColorizer, check to make sure docindex, url_func, etc. exist before using them. Modified Paths: -------------- trunk/epydoc/src/epydoc/docwriter/html.py trunk/epydoc/src/epydoc/docwriter/html_colorize.py Modified: trunk/epydoc/src/epydoc/docwriter/html.py =================================================================== --- trunk/epydoc/src/epydoc/docwriter/html.py 2006-08-23 02:04:55 UTC (rev 1299) +++ trunk/epydoc/src/epydoc/docwriter/html.py 2006-08-23 05:25:13 UTC (rev 1300) @@ -565,9 +565,22 @@ # Write source code files. if self._incl_sourcecode: + # Build a map from short names to APIDocs, used when + # linking names in the source code. + name_to_docs = {} + for api_doc in self.indexed_docs: + if (api_doc.canonical_name is not None and + self.url(api_doc) is not None): + name = api_doc.canonical_name[-1] + name_to_docs.setdefault(name, []).append(api_doc) + # Sort each entry of the name_to_docs list. + for doc_list in name_to_docs.values(): + doc_list.sort() + # Write the source code for each module. for doc in self.modules_with_sourcecode: filename = urllib.unquote(self.pysrc_url(doc)) - self._write(self.write_sourcecode, directory, filename, doc) + self._write(self.write_sourcecode, directory, filename, doc, + name_to_docs) # Write the index.html files. # (this must be done last, since it might copy another file) @@ -682,7 +695,7 @@ #{ 2.??. Source Code Pages #//////////////////////////////////////////////////////////// - def write_sourcecode(self, out, doc): + def write_sourcecode(self, out, doc, name_to_docs): filename = doc.filename name = str(doc.canonical_name) @@ -696,7 +709,7 @@ self.href(doc, label='%s %s' % (self.doc_kind(doc), name))) out('<pre class="py-src">\n') out(PythonSourceColorizer(filename, name, self.docindex, - self.indexed_docs, self.url).colorize()) + self.url, name_to_docs).colorize()) out('</pre>\n<br />\n') # Footer Modified: trunk/epydoc/src/epydoc/docwriter/html_colorize.py =================================================================== --- trunk/epydoc/src/epydoc/docwriter/html_colorize.py 2006-08-23 02:04:55 UTC (rev 1299) +++ trunk/epydoc/src/epydoc/docwriter/html_colorize.py 2006-08-23 05:25:13 UTC (rev 1300) @@ -488,7 +488,6 @@ </script> ''' - import tokenize, sys, token, cgi, keyword try: from cStringIO import StringIO except: from StringIO import StringIO @@ -602,7 +601,7 @@ GUESS_LINK_TARGETS = True def __init__(self, module_filename, module_name, - docindex=None, api_docs=None, url_func=None): + docindex=None, url_func=None, name_to_docs=None): """ Create a new HTML colorizer for the specified module. @@ -622,17 +621,18 @@ #: The dotted name of the module we're colorizing. self.module_name = module_name + #: A docindex, used to create href links from identifiers to + #: the API documentation for their values. self.docindex = docindex - #: A mapping from short names to lists of ValueDoc. - self.name_to_docs = {} - for api_doc in api_docs: - if (api_doc.canonical_name is not None and - url_func(api_doc) is not None): - name = api_doc.canonical_name[-1] - self.name_to_docs.setdefault(name,set()).add(api_doc) + #: A mapping from short names to lists of ValueDoc, used to + #: decide which values an identifier might map to when creating + #: href links from identifiers to the API docs for their values. + self.name_to_docs = name_to_docs - #: A function that maps APIDoc -> URL + #: A function that maps APIDoc -> URL, used to create href + #: links from identifiers to the API documentation for their + #: values. self.url_func = url_func #: The index in C{text} of the last character of the last @@ -935,7 +935,8 @@ # a function, then that function is our context, not # the namespace that contains it. [xx] this isn't always # the right thing to do. - if self.GUESS_LINK_TARGETS: + if (self.GUESS_LINK_TARGETS and self.docindex is not None + and self.url_func is not None): context = [n for n in self.context if n is not None] container = DottedName(self.module_name, *context) doc = self.docindex.get_vardoc(container+toktext) @@ -943,8 +944,9 @@ url = self.url_func(doc) # Otherwise, check the name_to_docs index to see what # else this name might refer to. - if url is None: - docs = sorted(self.name_to_docs.get(toktext, [])) + if (url is None and self.name_to_docs is not None + and self.url_func is not None): + docs = self.name_to_docs.get(toktext, []) if docs: tooltip='\n'.join([str(d.canonical_name) for d in docs]) @@ -1074,7 +1076,8 @@ elif isinstance(doc, StaticMethodDoc): return 'Static Method' elif isinstance(doc, RoutineDoc): - if isinstance(self.docindex.container(doc), ClassDoc): + if (self.docindex is not None and + isinstance(self.docindex.container(doc), ClassDoc)): return 'Method' else: return 'Function' This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-23 02:04:57
|
Revision: 1299 Author: edloper Date: 2006-08-22 19:04:55 -0700 (Tue, 22 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1299&view=rev Log Message: ----------- - Fixed bug in unreachable name handling introduced by previous commit (1298). Modified Paths: -------------- trunk/epydoc/src/epydoc/docbuilder.py Modified: trunk/epydoc/src/epydoc/docbuilder.py =================================================================== --- trunk/epydoc/src/epydoc/docbuilder.py 2006-08-23 00:21:43 UTC (rev 1298) +++ trunk/epydoc/src/epydoc/docbuilder.py 2006-08-23 02:04:55 UTC (rev 1299) @@ -952,13 +952,13 @@ L{assign_canonical_names()} finds a canonical name with a better score, then it will replace the old name.""" -_unreachable_names = {DottedName(DottedName.UNREACHABLE):2} +_unreachable_names = {DottedName(DottedName.UNREACHABLE):1} """The set of names that have been used for unreachable objects. This is used to ensure there are no duplicate cannonical names assigned. C{_unreachable_names} is a dictionary mapping from dotted names to integer ids, where the next unused unreachable name derived from dotted name C{n} is -C{DottedName('%s-%s' % (n, str(_unreachable_names[n]))}""" +C{DottedName('%s-%s' % (n, str(_unreachable_names[n]+1))}""" def assign_canonical_names(val_doc, name, docindex, score=0): """ @@ -1074,10 +1074,10 @@ # Uniquify the name. if name in _unreachable_names: - name = DottedName('%s-%s' % (name, _unreachable_names[name])) _unreachable_names[name] += 1 + name = DottedName('%s-%s' % (name, _unreachable_names[name]-1)) else: - _unreachable_names[name] = 2 + _unreachable_names[name] = 1 return name, -10000 This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-23 00:21:45
|
Revision: 1298 Author: edloper Date: 2006-08-22 17:21:43 -0700 (Tue, 22 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1298&view=rev Log Message: ----------- - Changed _unreachable_names to be a dictionary from name to integer id, which serves a minor optimization if a large number of unreachable names are used. Based on a patch provided by Daniel von Dincklage. Modified Paths: -------------- trunk/epydoc/src/epydoc/docbuilder.py Modified: trunk/epydoc/src/epydoc/docbuilder.py =================================================================== --- trunk/epydoc/src/epydoc/docbuilder.py 2006-08-22 21:46:27 UTC (rev 1297) +++ trunk/epydoc/src/epydoc/docbuilder.py 2006-08-23 00:21:43 UTC (rev 1298) @@ -952,9 +952,13 @@ L{assign_canonical_names()} finds a canonical name with a better score, then it will replace the old name.""" -_unreachable_names = set(DottedName(DottedName.UNREACHABLE)) +_unreachable_names = {DottedName(DottedName.UNREACHABLE):2} """The set of names that have been used for unreachable objects. This -is used to ensure there are no duplicate cannonical names assigned.""" +is used to ensure there are no duplicate cannonical names assigned. +C{_unreachable_names} is a dictionary mapping from dotted names to +integer ids, where the next unused unreachable name derived from +dotted name C{n} is +C{DottedName('%s-%s' % (n, str(_unreachable_names[n]))}""" def assign_canonical_names(val_doc, name, docindex, score=0): """ @@ -1070,11 +1074,10 @@ # Uniquify the name. if name in _unreachable_names: - n = 2 - while DottedName('%s-%s' % (name,n)) in _unreachable_names: - n += 1 - name = DottedName('%s-%s' % (name,n)) - _unreachable_names.add(name) + name = DottedName('%s-%s' % (name, _unreachable_names[name])) + _unreachable_names[name] += 1 + else: + _unreachable_names[name] = 2 return name, -10000 This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-22 21:46:30
|
Revision: 1297 Author: edloper Date: 2006-08-22 14:46:27 -0700 (Tue, 22 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1297&view=rev Log Message: ----------- - optimized DottedName.contextualize() and DottedName.dominates() for speed (based on patch provided by Daniel von Dincklage) Modified Paths: -------------- trunk/epydoc/src/epydoc/apidoc.py Modified: trunk/epydoc/src/epydoc/apidoc.py =================================================================== --- trunk/epydoc/src/epydoc/apidoc.py 2006-08-22 16:46:03 UTC (rev 1296) +++ trunk/epydoc/src/epydoc/apidoc.py 2006-08-22 21:46:27 UTC (rev 1297) @@ -192,9 +192,15 @@ >>> DottedName('a.b').dominates(DottedName('a.b.c.d')) True """ - if strict and len(self._identifiers)==len(name._identifiers): + len_self = len(self._identifiers) + len_name = len(name._identifiers) + + if (len_self > len_name) or (strict and len_self == len_name): return False - return self._identifiers == name._identifiers[:len(self)] + # The following is redundant (the first clause is implied by + # the second), but is done as an optimization. + return ((self._identifiers[0] == name._identifiers[0]) and + self._identifiers == name._identifiers[:len_self]) def contextualize(self, context): """ @@ -217,6 +223,22 @@ else: return self + # Find the first index where self & context differ. + for i in range(min(len(context), len(self))): + if self._identifiers[i] != context._identifiers[i]: + first_difference = i + break + else: + first_difference = i+1 + + # Strip off anything before that index. + if first_difference == 0: + return self + elif first_difference == len(self): + return self[-1:] + else: + return self[first_difference:] + ###################################################################### # UNKNOWN Value ###################################################################### This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-22 16:46:07
|
Revision: 1296 Author: edloper Date: 2006-08-22 09:46:03 -0700 (Tue, 22 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1296&view=rev Log Message: ----------- - Added regression tests to the web page Modified Paths: -------------- trunk/epydoc/Makefile Modified: trunk/epydoc/Makefile =================================================================== --- trunk/epydoc/Makefile 2006-08-22 16:45:49 UTC (rev 1295) +++ trunk/epydoc/Makefile 2006-08-22 16:46:03 UTC (rev 1296) @@ -13,6 +13,7 @@ PY_SRCFILES = $(shell find $(PY_SRC) -name '*.py') EXAMPLES_SRC = $(wildcard doc/*.py) DOCS = $(wildcard doc/*) +DOCTESTS = $(wildcard src/epydoc/test/*.doctest) # What version of python to use? PYTHON = python2.4 @@ -33,9 +34,11 @@ HTML_API = $(HTML)/api HTML_EXAMPLES = $(HTML)/examples HTML_STDLIB = $(HTML)/stdlib +HTML_DOCTEST = $(HTML)/doctest LATEX_API = $(LATEX)/api LATEX_STDLIB = $(LATEX)/stdlib + EPYDOC = $(PYTHON) src/epydoc/cli.py export PYTHONPATH=src/ @@ -53,6 +56,7 @@ @echo " make webpage -- build the webpage and copy it to sourceforge" @echo " make api-html -- build the HTML docs for epydoc" @echo " make api-pdf -- build the PDF docs for epydoc" + @echo " make doctest-html -- convert doctests to HTML" @echo " make examples -- build example API docs for the webpage" @echo " make stdlib-html -- build HTML docs for the Python Standard Library" @echo " make checkdocs -- check the documentation completeness" @@ -96,12 +100,14 @@ epydoc --check --tests=vars,types $(PY_SRC) .webpage.up2date: .api-html.up2date .examples.up2date .api-pdf.up2date \ - doc/epydoc-man.html doc/epydocgui-man.html $(DOCS) + .doctest-html.up2date doc/epydoc-man.html \ + doc/epydocgui-man.html $(DOCS) rm -rf $(WEBDIR) mkdir -p $(WEBDIR) cp -r $(DOCS) $(WEBDIR) cp -r $(HTML_API) $(WEBDIR)/api cp -r $(HTML_EXAMPLES) $(WEBDIR)/examples + cp -r $(HTML_DOCTEST) $(WEBDIR)/doctest cp $(LATEX_API)/api.pdf $(WEBDIR)/epydoc.pdf touch .webpage.up2date @@ -127,6 +133,18 @@ --name "Epydoc $(VERSION)" $(PY_SRC) -v touch .api-pdf.up2date +doctest-html: .doctests.up2date +.doctest-html.up2date: $(DOCTESTS) + rm -rf $(HTML_DOCTEST) + mkdir -p $(HTML_DOCTEST) + @for doctest in $(DOCTESTS); do \ + out_file=$(HTML_DOCTEST)/`basename $$doctest .doctest`.html; \ + echo rst2html $$doctest $$out_file; \ + if rst2html $$doctest $$out_file; then true; \ + else exit 1; fi\ + done + touch .doctest-html.up2date + examples: .examples.up2date .examples.up2date: $(EXAMPLES_SRC) $(PY_SRCFILES) rm -rf $(HTML_EXAMPLES) This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-22 16:45:55
|
Revision: 1295 Author: edloper Date: 2006-08-22 09:45:49 -0700 (Tue, 22 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1295&view=rev Log Message: ----------- - Added regression tests to the web page Modified Paths: -------------- trunk/epydoc/doc/index.html Added Paths: ----------- trunk/epydoc/doc/doctests.html Added: trunk/epydoc/doc/doctests.html =================================================================== --- trunk/epydoc/doc/doctests.html (rev 0) +++ trunk/epydoc/doc/doctests.html 2006-08-22 16:45:49 UTC (rev 1295) @@ -0,0 +1,62 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> <head> +<title>Epydoc: Regression Tests</title> +<link rel="stylesheet" href="epydoc.css" type="text/css"/> +</head> +<!-- $Id: future.html 1211 2006-04-10 19:38:37Z edloper $ --> + +<body> +<div class="body"> +<h1> Epydoc: Regression Tests </h1> + +<p> The following files contain the current regression test suite for +epydoc. Each file contains a prose description of some aspect of +epydoc, interspersed with +<a href="http://docs.python.org/lib/module-doctest.html">doctest</a> +examples. Each of these doctest examples is a single test case. </p> + +<ul> + <li> <a href="doctest/apidoc.html">APIDoc</a> -- The classes used + to encode API documentation about Python programs.</li> + <li> <a href="doctest/docintrospecter.html">Introspection</a> -- + Extracting API information about Python objects by directly + introspecting their values.</li> + <li> <a href="doctest/docparser.html">Source Code Parsing</a> -- + Extracting API information about Python objects by parsing + their source code.</li> + <li> <a href="doctest/encoding.html">Unicode & Encodings</a> -- + Tests for the processing of Python files that use non-ascii + encodings. </li> + <li> <a href="doctest/epytext.html">Epytext</a> -- The default + markup language used by epydoc.</li> +</ul> + +</div> +<table width="100%" class="navbox" cellpadding="1" cellspacing="0"> + <tr> + <a class="nav" href="index.html"> + <td align="center" width="20%" class="nav"> + <a class="nav" href="index.html"> + Home</a></td></a> + <a class="nav" href="installing.html"> + <td align="center" width="20%" class="nav"> + <a class="nav" href="installing.html"> + Installing Epydoc</a></td></a> + <a class="nav" href="using.html"> + <td align="center" width="20%" class="nav"> + <a class="nav" href="using.html"> + Using Epydoc</a></td></a> + <a class="nav" href="epytext.html"> + <td align="center" width="20%" class="nav"> + <a class="nav" href="epytext.html"> + Epytext</a></td></a> + <td align="center" width="20%" class="nav"> + + <A href="http://sourceforge.net/projects/epydoc"> + <IMG src="sflogo.png" + width="88" height="26" border="0" alt="SourceForge" + align="top"/></A></td> + </tr> +</table> +</body> +</html> Modified: trunk/epydoc/doc/index.html =================================================================== --- trunk/epydoc/doc/index.html 2006-08-22 16:44:27 UTC (rev 1294) +++ trunk/epydoc/doc/index.html 2006-08-22 16:45:49 UTC (rev 1295) @@ -78,6 +78,7 @@ <li> <a href="history.html">History</a> </li> <li> <a href="future.html">Future Directions</a> </li> <li> <a href="relatedprojects.html">Related Projects</a> </li> + <li> <a href="doctests.html">Regression Tests</a> </li> </ul></p> </div> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-22 16:44:29
|
Revision: 1294 Author: edloper Date: 2006-08-22 09:44:27 -0700 (Tue, 22 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1294&view=rev Log Message: ----------- - Use 'tight' parse repr for default values. Modified Paths: -------------- trunk/epydoc/src/epydoc/docparser.py Modified: trunk/epydoc/src/epydoc/docparser.py =================================================================== --- trunk/epydoc/src/epydoc/docparser.py 2006-08-22 16:43:07 UTC (rev 1293) +++ trunk/epydoc/src/epydoc/docparser.py 2006-08-22 16:44:27 UTC (rev 1294) @@ -1449,7 +1449,8 @@ elif arg[1] != (token.OP, '=') or len(arg) == 2: raise ParseError("Bad argument list") else: - default_val = GenericValueDoc(parse_repr=pp_toktree(arg[2:]), + default_repr = pp_toktree(arg[2:], 'tight') + default_val = GenericValueDoc(parse_repr=default_repr, docs_extracted_by='parser') func_doc.posarg_defaults.append(default_val) This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-22 16:43:12
|
Revision: 1293 Author: edloper Date: 2006-08-22 09:43:07 -0700 (Tue, 22 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1293&view=rev Log Message: ----------- - Changed page title formatting to make rst happy. - Updated docparser tests to reflect the fact that the parse_repr field now uses normal (not tight) spacing. - Updated the encoding examples. Modified Paths: -------------- trunk/epydoc/src/epydoc/test/apidoc.doctest trunk/epydoc/src/epydoc/test/docintrospecter.doctest trunk/epydoc/src/epydoc/test/docparser.doctest trunk/epydoc/src/epydoc/test/encoding.doctest trunk/epydoc/src/epydoc/test/epytext.doctest Modified: trunk/epydoc/src/epydoc/test/apidoc.doctest =================================================================== --- trunk/epydoc/src/epydoc/test/apidoc.doctest 2006-08-22 15:11:17 UTC (rev 1292) +++ trunk/epydoc/src/epydoc/test/apidoc.doctest 2006-08-22 16:43:07 UTC (rev 1293) @@ -1,5 +1,5 @@ - Regression Testing for epydoc.apidoc - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Regression Testing for epydoc.apidoc +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This file serves to provide both documentation and regression tests for the epydoc.apidoc module. The main purpose of this module is to define the `APIDoc` class hierarchy, which is used to encode API Modified: trunk/epydoc/src/epydoc/test/docintrospecter.doctest =================================================================== --- trunk/epydoc/src/epydoc/test/docintrospecter.doctest 2006-08-22 15:11:17 UTC (rev 1292) +++ trunk/epydoc/src/epydoc/test/docintrospecter.doctest 2006-08-22 16:43:07 UTC (rev 1293) @@ -1,5 +1,5 @@ - Regression Testing for epydoc.docintrospecter - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Regression Testing for epydoc.docintrospecter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The `epydoc.docintrospecter` module is used to extract API documentation by introspecting Python objects directy. Its primary interface is `introspect_docs()`, which takes a Python object, and returns a Modified: trunk/epydoc/src/epydoc/test/docparser.doctest =================================================================== --- trunk/epydoc/src/epydoc/test/docparser.doctest 2006-08-22 15:11:17 UTC (rev 1292) +++ trunk/epydoc/src/epydoc/test/docparser.doctest 2006-08-22 16:43:07 UTC (rev 1293) @@ -1,5 +1,5 @@ - Regression Testing for epydoc.docparser - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Regression Testing for epydoc.docparser +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The `epydoc.docparser` module is used to extract API documentation by parsing the source code of Python files. Its primary interface is `parse_docs()`, which takes a module's filename, and returns a @@ -101,7 +101,7 @@ | +- defining_module | | +- ModuleDoc for test [0] (defined above) | +- docs_extracted_by = 'parser' - | +- parse_repr = u'[1,2,3]+ [4,5]' + | +- parse_repr = u'[1, 2, 3]+ [4, 5]' | +- toktree = [[(51, u'['), (2, u'1'), (51, u','), ... +- z => VariableDoc for test.z [5] +- container @@ -117,7 +117,7 @@ +- defining_module | +- ModuleDoc for test [0] (defined above) +- docs_extracted_by = 'parser' - +- parse_repr = u'f(x,y)' + +- parse_repr = u'f(x, y)' +- toktree = [(1, u'f'), [(51, u'('), (1, u'x'), (... In this example, DocParser decides that the assignment to y is @@ -136,7 +136,7 @@ | +- name = u'x' | +- value | +- GenericValueDoc [2] - | +- parse_repr = u'[1,2]' + | +- parse_repr = u'[1, 2]' +- y => VariableDoc for test.y [3] +- is_alias = True +- name = u'y' @@ -233,17 +233,19 @@ ===================== DocParser will look inside certain types of module-level control blocks. By default, DocParser looks inside the following block types: - - if blocks - - elif blocks - - else blocks - - try blocks - - except blocks - - finally blocks +- if blocks +- elif blocks +- else blocks +- try blocks +- except blocks +- finally blocks + By default, DocParse does not look inside the following block types: - - while blocks - - for blocks +- while blocks +- for blocks + >>> # DocParser looks inside if/elif/else blocks. >>> runparser(s=""" ... if condition: @@ -409,6 +411,7 @@ ... """, show="f", exclude='defining_module') RoutineDoc for test.f [0] +- canonical_name = DottedName('test', u'f') + +- decorators = [] +- docs_extracted_by = 'parser' +- docstring = u'docstring for f' +- docstring_lineno = 3 @@ -433,6 +436,7 @@ ... """, show="f", exclude='defining_module') RoutineDoc for test.f [0] +- canonical_name = DottedName('test', u'f') + +- decorators = [] +- docs_extracted_by = 'parser' +- docstring = u'docstring for f' +- docstring_lineno = 3 @@ -448,6 +452,7 @@ ... """, show="f", exclude='defining_module') RoutineDoc for test.f [0] +- canonical_name = DottedName('test', u'f') + +- decorators = [] +- docs_extracted_by = 'parser' +- kwarg = None +- lineno = 2 Modified: trunk/epydoc/src/epydoc/test/encoding.doctest =================================================================== --- trunk/epydoc/src/epydoc/test/encoding.doctest 2006-08-22 15:11:17 UTC (rev 1292) +++ trunk/epydoc/src/epydoc/test/encoding.doctest 2006-08-22 16:43:07 UTC (rev 1293) @@ -1,5 +1,5 @@ - End-to-end Tests for Unicode Encoding - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +End-to-end Tests for Unicode Encoding +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Test Function ============= The following function is used as an end-to-end test for unicode @@ -115,23 +115,23 @@ >>> # UTF-8 with a coding directive: >>> test("# -*- coding: utf-8 -*-\n"+utf8_test) <p>abc ABC 123</p> - <p>0x80-0x7ff range: €  ߾ ߿</p> - <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x80-0x7ff range: €  ߾ ߿</p> + <p>0x800-0xffff range: ࠀ ࠁ  </p> + 0x10000-0x10ffff range: 𐀀 𐀁   >>> # UTF-8 with a BOM & a coding directive: >>> test(utf8_bom+"# -*- coding: utf-8 -*-\n"+utf8_test) <p>abc ABC 123</p> - <p>0x80-0x7ff range: €  ߾ ߿</p> - <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x80-0x7ff range: €  ߾ ߿</p> + <p>0x800-0xffff range: ࠀ ࠁ  </p> + 0x10000-0x10ffff range: 𐀀 𐀁   >>> # UTF-8 with a BOM & no coding directive: >>> test(utf8_bom+utf8_test) <p>abc ABC 123</p> - <p>0x80-0x7ff range: €  ߾ ߿</p> - <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x80-0x7ff range: €  ߾ ߿</p> + <p>0x800-0xffff range: ࠀ ࠁ  </p> + 0x10000-0x10ffff range: 𐀀 𐀁   Tests for KOI8-R: @@ -154,15 +154,15 @@ >>> test("\n# -*- coding: utf-8 -*-\n"+utf8_test) <p>abc ABC 123</p> - <p>0x80-0x7ff range: €  ߾ ߿</p> - <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x80-0x7ff range: €  ߾ ߿</p> + <p>0x800-0xffff range: ࠀ ࠁ  </p> + 0x10000-0x10ffff range: 𐀀 𐀁   >>> test("# comment\n# -*- coding: utf-8 -*-\n"+utf8_test) <p>abc ABC 123</p> - <p>0x80-0x7ff range: €  ߾ ߿</p> - <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x80-0x7ff range: €  ߾ ߿</p> + <p>0x800-0xffff range: ࠀ ࠁ  </p> + 0x10000-0x10ffff range: 𐀀 𐀁   Tests for shift-jis @@ -187,11 +187,12 @@ Under special circumstances, we may not be able to tell what the proper encoding for a docstring is. This happens if: - 1. the docstring is only available via introspection. - 2. we are unable to determine what module the object that owns - the docstring came from. - 3. the docstring contains non-ascii characters +1. the docstring is only available via introspection. +2. we are unable to determine what module the object that owns + the docstring came from. +3. the docstring contains non-ascii characters + Under these circumstances, we issue a warning, and treat the docstring as latin-1. An example of this is a non-unicode docstring for properties: @@ -210,35 +211,35 @@ >>> test("# -*- coding: utf-8 -*-\n"+utf8_test, introspect=False) <p>abc ABC 123</p> - <p>0x80-0x7ff range: €  ߾ ߿</p> - <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x80-0x7ff range: €  ߾ ߿</p> + <p>0x800-0xffff range: ࠀ ࠁ  </p> + 0x10000-0x10ffff range: 𐀀 𐀁   >>> test(utf8_bom+"# -*- coding: utf-8 -*-\n"+utf8_test, introspect=False) <p>abc ABC 123</p> - <p>0x80-0x7ff range: €  ߾ ߿</p> - <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x80-0x7ff range: €  ߾ ߿</p> + <p>0x800-0xffff range: ࠀ ࠁ  </p> + 0x10000-0x10ffff range: 𐀀 𐀁   >>> test(utf8_bom+utf8_test, introspect=False) <p>abc ABC 123</p> - <p>0x80-0x7ff range: €  ߾ ߿</p> - <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x80-0x7ff range: €  ߾ ߿</p> + <p>0x800-0xffff range: ࠀ ࠁ  </p> + 0x10000-0x10ffff range: 𐀀 𐀁   >>> test("# -*- coding: utf-8 -*-\n"+utf8_test, parse=False) <p>abc ABC 123</p> - <p>0x80-0x7ff range: €  ߾ ߿</p> - <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x80-0x7ff range: €  ߾ ߿</p> + <p>0x800-0xffff range: ࠀ ࠁ  </p> + 0x10000-0x10ffff range: 𐀀 𐀁   >>> test(utf8_bom+"# -*- coding: utf-8 -*-\n"+utf8_test, parse=False) <p>abc ABC 123</p> - <p>0x80-0x7ff range: €  ߾ ߿</p> - <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x80-0x7ff range: €  ߾ ߿</p> + <p>0x800-0xffff range: ࠀ ࠁ  </p> + 0x10000-0x10ffff range: 𐀀 𐀁   >>> test(utf8_bom+utf8_test, parse=False) <p>abc ABC 123</p> - <p>0x80-0x7ff range: €  ߾ ߿</p> - <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x80-0x7ff range: €  ߾ ߿</p> + <p>0x800-0xffff range: ࠀ ࠁ  </p> + 0x10000-0x10ffff range: 𐀀 𐀁   Context checks ============== Modified: trunk/epydoc/src/epydoc/test/epytext.doctest =================================================================== --- trunk/epydoc/src/epydoc/test/epytext.doctest 2006-08-22 15:11:17 UTC (rev 1292) +++ trunk/epydoc/src/epydoc/test/epytext.doctest 2006-08-22 16:43:07 UTC (rev 1293) @@ -1,5 +1,5 @@ - Regression Testing for epytext - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Regression Testing for epytext +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These tests were taken pretty much verbatim out of the old unittests from epydoc 2.1. They could use some serious updating, when I get the time, esp. given that it's so much easier to write tests with doctest This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-22 15:11:20
|
Revision: 1292 Author: edloper Date: 2006-08-22 08:11:17 -0700 (Tue, 22 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1292&view=rev Log Message: ----------- - Added FAQ entry for testing if epydoc is currently running Modified Paths: -------------- trunk/epydoc/doc/faq.html Modified: trunk/epydoc/doc/faq.html =================================================================== --- trunk/epydoc/doc/faq.html 2006-08-22 07:31:56 UTC (rev 1291) +++ trunk/epydoc/doc/faq.html 2006-08-22 15:11:17 UTC (rev 1292) @@ -28,6 +28,8 @@ introspection and parsing?</a></li> <li><a href="#parse_only">When should I use <code>--parse-only</code>? </a></li> + <li><a href="#is_epydoc_running">How can I test whether + epydoc is currently running?</a></li> </ul></p> <p><b>Generated Output</b> <ul class="nomargin"> @@ -175,9 +177,26 @@ non-windows machine). </li> <li>You wish to document a module where importing the module would have undesired side effects.</li> - </ul> + </ul></dd> - + <!-- QUESTION --><a name="is_epydoc_running" /> + <dt> <p><b>Q:</b> How can I test whether my program is + being documented by epydoc? + </p></dt> + + <dd> <p>Some programs or libraries need to take special actions when + being documented by epydoc. E.g., you might want your code to skip + certain set-up actions if it's just being imported to be documented. + You can test whether epydoc is currently running by testing whether + <code>'epydoc'</code> is in <code>sys.modules</code>:</p> + +<div class="screen"><pre> + >>> import sys.modules + >>> if 'epydoc' in sys.modules: + ... print 'Epydoc is running' +</pre></div> + </dd> + </dl> <!-- ==================== GENERATED OUTPUT ========================= --> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-22 07:32:07
|
Revision: 1291 Author: edloper Date: 2006-08-22 00:31:56 -0700 (Tue, 22 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1291&view=rev Log Message: ----------- - Generalized metadata index code. - Added metadata indices for @deprecated and @since. 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-08-22 06:36:54 UTC (rev 1290) +++ trunk/epydoc/src/epydoc/docwriter/html.py 2006-08-22 07:31:56 UTC (rev 1291) @@ -412,7 +412,8 @@ for doc in self.module_list: if isinstance(doc, ModuleDoc) and is_src_filename(doc.filename): self.modules_with_sourcecode.add(doc) - self._num_files = len(self.class_list) + 2*len(self.module_list) + 14 + self._num_files = (len(self.class_list) + 2*len(self.module_list) + + 11 + len(self.METADATA_INDICES)) if self._incl_sourcecode: self._num_files += len(self.modules_with_sourcecode) @@ -512,10 +513,9 @@ # Write the term & identifier indices indices = {'ident': self.build_identifier_index(), - 'term': self.build_term_index(), - 'bug': self.build_metadata_index('bug'), - 'todo': self.build_metadata_index('todo'), - 'change': self.build_metadata_index('change')} + 'term': self.build_term_index()} + for (name, label, label2) in self.METADATA_INDICES: + indices[name] = self.build_metadata_index(name) self._write(self.write_link_index, directory, 'identifier-index.html', indices, 'Identifier Index', 'identifier-index.html', 'ident') @@ -525,21 +525,14 @@ 'term-index.html', 'term') else: self._files_written += 1 # (skipped) - if indices['bug']: - self._write(self.write_metadata_index, directory, - 'bug-index.html', indices, 'bug', 'Bug List') - else: - self._files_written += 1 # (skipped) - if indices['todo']: - self._write(self.write_metadata_index, directory, - 'todo-index.html', indices, 'todo', 'To Do List') - else: - self._files_written += 1 # (skipped) - if indices['change']: - self._write(self.write_metadata_index, directory, - 'change-index.html', indices, 'change', 'Change Log') - else: - self._files_written += 1 # (skipped) + for (name, label, label2) in self.METADATA_INDICES: + if indices[name]: + self._write(self.write_metadata_index, directory, + '%s-index.html' % name, indices, name, + label, label2) + else: + self._files_written += 1 # (skipped) + # Write the trees file (package & class hierarchies) if self.module_list: @@ -597,7 +590,10 @@ log.docstring_warning(estr) # [xx] testing: - assert self._num_files == self._files_written + if self._num_files != int(self._files_written): + log.debug("Expected to write %d files, but actually " + "wrote %d files" % + (self._num_files, int(self._files_written))) def _write(self, write_func, directory, filename, *args): # Display our progress. @@ -940,7 +936,7 @@ self.write_navbar(out, 'indices') self.write_footer(out) - def write_metadata_index(self, out, indices, field, title): + def write_metadata_index(self, out, indices, field, title, typ): """ Write an HTML page containing a metadata index. """ @@ -973,7 +969,8 @@ out('<div>\n') out('<table width="100%" class="metadata-index" ' 'bgcolor="#e0e0e0"><tr><td class="metadata-index">') - out('<b>In %s</b>' % self.href(doc, label=doc.canonical_name)) + out('<b>%s in %s</b>' % + (typ, self.href(doc, label=doc.canonical_name))) out(' <ul class="nomargin">\n') for descr in descrs: out(' <li>%s</li>\n' % @@ -996,19 +993,17 @@ self.write_header(out, title) self.write_navbar(out, 'indices') self.write_breadcrumbs(out, 'indices', url) - - if (indices['term'] or indices['bug'] or - indices['todo'] or indices['change']): + + if (indices['term'] or + [1 for (name,l,l2) in self.METADATA_INDICES if indices[name]]): out('<center><b>[\n') - out(' <a href="identifier-index.html">Identifier Index</a>\n') + out(' <a href="identifier-index.html">Identifiers</a>\n') if indices['term']: - out('| <a href="term-index.html">Term Definition Index</a>\n') - if indices['bug']: - out('| <a href="bug-index.html">Bug List</a>\n') - if indices['todo']: - out('| <a href="todo-index.html">To Do List</a>\n') - if indices['change']: - out('| <a href="change-index.html">Change Log</a>\n') + out('| <a href="term-index.html">Term Definitions</a>\n') + for (name, label, label2) in self.METADATA_INDICES: + if indices[name]: + out('| <a href="%s-index.html">%s</a>\n' % + (name, label2)) out(']</b></center><br />\n') def write_index_section(self, out, items, add_blankline=False): @@ -2685,6 +2680,18 @@ #//////////////////////////////////////////////////////////// #{ Index generation #//////////////////////////////////////////////////////////// + + #: A list of metadata indices that should be generated. Each + #: entry in this list is a tuple C{(tag, label, short_label)}, + #: where C{tag} is the cannonical tag of a metadata field; + #: C{label} is a label for the index page; and C{short_label} + #: is a shorter label, used in the index selector. + METADATA_INDICES = [('bug', 'Bug List', 'Bugs'), + ('todo', 'To Do List', 'To Do'), + ('change', 'Change Log', 'Changes'), + ('deprecated', 'Deprecation List', 'Deprecations'), + ('since', 'Introductions List', 'Introductions'), + ] def build_identifier_index(self): items = [] This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-22 06:36:57
|
Revision: 1290 Author: edloper Date: 2006-08-21 23:36:54 -0700 (Mon, 21 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1290&view=rev Log Message: ----------- - Added index for @change (Change Log). - Fixed bug in metadata indices where variables were listed with their short names, instead of their full canonical names. 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-08-22 06:28:21 UTC (rev 1289) +++ trunk/epydoc/src/epydoc/docwriter/html.py 2006-08-22 06:36:54 UTC (rev 1290) @@ -412,7 +412,7 @@ for doc in self.module_list: if isinstance(doc, ModuleDoc) and is_src_filename(doc.filename): self.modules_with_sourcecode.add(doc) - self._num_files = len(self.class_list) + 2*len(self.module_list) + 13 + self._num_files = len(self.class_list) + 2*len(self.module_list) + 14 if self._incl_sourcecode: self._num_files += len(self.modules_with_sourcecode) @@ -514,7 +514,8 @@ indices = {'ident': self.build_identifier_index(), 'term': self.build_term_index(), 'bug': self.build_metadata_index('bug'), - 'todo': self.build_metadata_index('todo')} + 'todo': self.build_metadata_index('todo'), + 'change': self.build_metadata_index('change')} self._write(self.write_link_index, directory, 'identifier-index.html', indices, 'Identifier Index', 'identifier-index.html', 'ident') @@ -534,6 +535,11 @@ 'todo-index.html', indices, 'todo', 'To Do List') else: self._files_written += 1 # (skipped) + if indices['change']: + self._write(self.write_metadata_index, directory, + 'change-index.html', indices, 'change', 'Change Log') + else: + self._files_written += 1 # (skipped) # Write the trees file (package & class hierarchies) if self.module_list: @@ -967,7 +973,7 @@ out('<div>\n') out('<table width="100%" class="metadata-index" ' 'bgcolor="#e0e0e0"><tr><td class="metadata-index">') - out('<b>In %s</b>' % self.href(doc)) + out('<b>In %s</b>' % self.href(doc, label=doc.canonical_name)) out(' <ul class="nomargin">\n') for descr in descrs: out(' <li>%s</li>\n' % @@ -991,7 +997,8 @@ self.write_navbar(out, 'indices') self.write_breadcrumbs(out, 'indices', url) - if indices['term'] or indices['bug'] or indices['todo']: + if (indices['term'] or indices['bug'] or + indices['todo'] or indices['change']): out('<center><b>[\n') out(' <a href="identifier-index.html">Identifier Index</a>\n') if indices['term']: @@ -1000,6 +1007,8 @@ out('| <a href="bug-index.html">Bug List</a>\n') if indices['todo']: out('| <a href="todo-index.html">To Do List</a>\n') + if indices['change']: + out('| <a href="change-index.html">Change Log</a>\n') out(']</b></center><br />\n') def write_index_section(self, out, items, add_blankline=False): This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-22 06:28:25
|
Revision: 1289 Author: edloper Date: 2006-08-21 23:28:21 -0700 (Mon, 21 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1289&view=rev Log Message: ----------- - Added docs for @change field - Updated docs to reflect the fact that __extra_epydoc_fields is deprecated, and @newfields should be used instead. Modified Paths: -------------- trunk/epydoc/doc/fields.html Modified: trunk/epydoc/doc/fields.html =================================================================== --- trunk/epydoc/doc/fields.html 2006-08-22 06:15:35 UTC (rev 1288) +++ trunk/epydoc/doc/fields.html 2006-08-22 06:28:21 UTC (rev 1289) @@ -224,6 +224,10 @@ <code>@<b>status</b>:</code> ... </td><td> The current status of an object.</td></tr> + <tr><td width="10%" align="left" valign="top"> + <code>@<b>change</b>:</code> ... </td><td> + A change log entry for this object.</td></tr> + <!-- ========== Formal Conditions ========== --> <tr><th colspan="2" align="left">Formal Conditions</th></tr> <tr><td width="10%" align="left" valign="top"> @@ -426,6 +430,10 @@ <tr><td align="left" valign="top"> <b><code>@copyright:</code> ...</b> </td><td> <code>@(c):</code> ... </td></tr> + + <tr><td align="left" valign="top"> + <b><code>@change:</code> ...</b> </td><td> + <code>@changed:</code> ... </td></tr> </table> </td></tr></table> </center> @@ -433,34 +441,27 @@ <a name="newfield"> <h2> 4. Adding New Fields</h2></a> -<p> New fields can be defined for the docstrings in a module with the -special module-level variable "<code>__extra_epydoc_fields__</code>". -This variable should contain a list of field specifications, where -each field specification is one of the following: </p> +<p> New fields can be defined for the docstrings in a module using the +special <code>@newfield</code> tag (or its synonym, +<code>@deffield</code>). This tag has the following syntax:</p> -<ul> - <li> A single string, which defines both the tag and the label for - the field. </li> - - <li> A tuple <code>(tag, label)</code>, where <code>tag</code> is - the field's tag, and <code>label</code> is its label. - - <li> A tuple <code>(tag, singular, plural)</code>, where - <code>tag</code> is the field's tag, <code>singular</code> is the - label that is used when the field has one entry, and - <code>plural</code> is the label that is used when the field has - multiple entries. </li> -</ul> +<div class="screen"><pre> +<b>@newfield <i>tag</i>:</b> <i>label</i> [, <i>plural</i>] +</pre></div> -<p> The following example illustrates how the special variable -"<code>__extra_epydoc_fields__"</code> can be used: </p> +<p>Where <code><i>tag</i></code> is the new tag that's being defined; +<code><i>label</i></code> is a string that will be used to mark this +field in the generated output; and <code><i>plural</i></code> is the +plural form of <code><i>label</i></code>, if different. The following +example illustrates how the <code>@newfield</code> can be used: </p> <table border="1" cellspacing="0" cellpadding="3" width="95%"> <tr><th width="50%">Docstring Input</th><th width="50%">Rendered Output</th> <tr valign="top"><td> <pre> -__extra_epydoc_fields__ = [ - ('corpus', 'Corpus', 'Corpora')] +""" +@newfield corpus: Corpus, Corpora +""" <code class="keyword">def</code> <code class="function">example</code>(): <code class="string">""" @@ -479,13 +480,9 @@ </td></tr> </table> -<p> New fields can also be defined for an individual docstring, using -the special <code>@newfield</code> field. In particular, -"<code>@newfield <i>tag</i>: <i>label</i> [, <i>plural</i>]</code>" will -define a new field, whose tag is <code><i>tag</i></code>; and which is -labeled in output documentation as <code><i>label</i></code>. The -optional argument <code><i>plural</i></code> specifies the label that -should be used if the field has multiple entries. </p> +<p><b>Note:</b> The module-level variable +<code>__extra_epydoc_fields__</code> is deprecated; use +<code>@newfield</code> instead.</p> <h2> 5. Markup-Specific Notes </h2> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-22 06:15:39
|
Revision: 1288 Author: edloper Date: 2006-08-21 23:15:35 -0700 (Mon, 21 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1288&view=rev Log Message: ----------- - Added metadata sections for variable & property details sections. - Rearranged the property details section a little. 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-08-22 06:00:44 UTC (rev 1287) +++ trunk/epydoc/src/epydoc/docwriter/html.py 2006-08-22 06:15:35 UTC (rev 1288) @@ -2152,18 +2152,19 @@ <h3 class="epydoc">$var_doc.name$</h3> $descr$ <dl><dt></dt><dd> - >>> if prop_doc.type_descr not in (None, UNKNOWN): - <dl><dt>Type:</dt> - <dd>$self.type_descr(var_doc, indent=6)$</dd></dl> - >>> #endif >>> for (name, val, summary) in accessors: - <dt>$name$ Method:</dt> + <dl><dt>$name$ Method:</dt> <dd>$val$ >>> if summary: - $summary$ >>> #endif - </dd> + </dd></dl> >>> #endfor + >>> if prop_doc.type_descr not in (None, UNKNOWN): + <dl><dt>Type:</dt> + <dd>$self.type_descr(var_doc, indent=6)$</dd></dl> + >>> #endif + >>> self.write_standard_fields(out, prop_doc) </dd></dl> </td></tr></table> </div> @@ -2187,6 +2188,7 @@ <dl><dt>Type:</dt> <dd>$self.type_descr(var_doc, indent=6)$</dd></dl> >>> #endif + >>> self.write_standard_fields(out, var_doc) >>> if var_doc.value is not UNKNOWN: <dl><dt>Value:</dt> <dd><table><tr><td><pre class="variable"> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-22 06:00:48
|
Revision: 1287 Author: edloper Date: 2006-08-21 23:00:44 -0700 (Mon, 21 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1287&view=rev Log Message: ----------- - Added a 'change log' field. Modified Paths: -------------- trunk/epydoc/src/epydoc/docstringparser.py Modified: trunk/epydoc/src/epydoc/docstringparser.py =================================================================== --- trunk/epydoc/src/epydoc/docstringparser.py 2006-08-22 05:43:19 UTC (rev 1286) +++ trunk/epydoc/src/epydoc/docstringparser.py 2006-08-22 06:00:44 UTC (rev 1287) @@ -133,6 +133,9 @@ # When was it introduced (version # or date) DocstringField(['since'], 'Since', multivalue=0), + # Changes made + DocstringField(['change', 'changed'], 'Change Log'), + # Crossreferences DocstringField(['see', 'seealso'], 'See Also', short=1), This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-22 05:43:23
|
Revision: 1286 Author: edloper Date: 2006-08-21 22:43:19 -0700 (Mon, 21 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1286&view=rev Log Message: ----------- - Replaced the previous linewrap marker (a colored backslash) with an image (crarr.png). The image is written by the write_images() method. 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-08-22 01:44:36 UTC (rev 1285) +++ trunk/epydoc/src/epydoc/docwriter/html.py 2006-08-22 05:43:19 UTC (rev 1286) @@ -12,7 +12,7 @@ """ __docformat__ = 'epytext en' -import re, os, sys, codecs, sre_constants, pprint +import re, os, sys, codecs, sre_constants, pprint, base64 import urllib from epydoc.apidoc import * import epydoc.docstringparser @@ -188,6 +188,8 @@ # 2.7. Homepage (index.html) # 2.8. CSS Stylesheet # 2.9. Javascript file + # 2.10. Graphs + # 2.11. Images # # 3. Page Element Generation -- write pieces of a web page file # 3.1. Page Header @@ -505,6 +507,9 @@ log.progress(self._files_written/self._num_files, 'epydoc.js') self.write_javascript(directory) + # Write images. + self.write_images(directory) + # Write the term & identifier indices indices = {'ident': self.build_identifier_index(), 'term': self.build_term_index(), @@ -1448,6 +1453,28 @@ 'call graph</a></span> ' % callgraph.uid) #//////////////////////////////////////////////////////////// + #{ 2.11. Images + #//////////////////////////////////////////////////////////// + + IMAGES = {'crarr.png': # Carriage-return arrow, used for LINEWRAP. + 'iVBORw0KGgoAAAANSUhEUgAAABEAAAAKCAMAAABlokWQAAAALHRFWHRD' + 'cmVhdGlvbiBUaW1lAFR1\nZSAyMiBBdWcgMjAwNiAwMDo0MzoxMCAtMD' + 'UwMGAMEFgAAAAHdElNRQfWCBYFASkQ033WAAAACXBI\nWXMAAB7CAAAe' + 'wgFu0HU+AAAABGdBTUEAALGPC/xhBQAAAEVQTFRF////zcOw18/AgGY0' + 'c1cg4dvQ\ninJEYEAAYkME3NXI6eTcloFYe2Asr5+AbE4Uh29A9fPwqp' + 'l4ZEUI8O3onopk0Ma0lH5U1nfFdgAA\nAAF0Uk5TAEDm2GYAAABNSURB' + 'VHjaY2BAAbzsvDAmK5oIlxgfioiwCAe7KJKIgKAQOzsLLwTwA0VY\n+d' + 'iRAT8T0AxuIIMHqoaXCWIPGzsHJ6orGJiYWRjQASOcBQAocgMSPKMTIg' + 'AAAABJRU5ErkJggg==\n', + } + + def write_images(self, directory): + for (name, data) in self.IMAGES.items(): + f = open(os.path.join(directory, name), 'w') + f.write(base64.decodestring(data)) + f.close() + + #//////////////////////////////////////////////////////////// #{ 3.1. Page Header #//////////////////////////////////////////////////////////// @@ -2273,7 +2300,8 @@ function treats HTML entities (e.g., C{&}) as single characters; and ignores HTML tags (e.g., C{<p>}). """ - LINEWRAP_MARKER = r'<span class="variable-linewrap">\</span>' + LINEWRAP_MARKER = (r'<span class="variable-linewrap">' + '<img src="crarr.png" alt="\" /></span>') ELLIPSIS_MARKER = r'<span class="variable-ellipsis">...</span>' open_elements = [] # tag stack This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
