Revision: 1489
http://svn.sourceforge.net/epydoc/?rev=1489&view=rev
Author: edloper
Date: 2007-02-13 17:20:09 -0800 (Tue, 13 Feb 2007)
Log Message:
-----------
- Added support for extracting metadata fields from __variables__. To
add a new __varaible__->field mapping, set the 'varnames'
variable of the field. Currently supported __variables__ are
__version__, __date__, __author__, __authors__, __license__.
Feel free to add more. Currently, __variables__ are required to have
string values to be considered for addition to metadata.
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docstringparser.py
Modified: trunk/epydoc/src/epydoc/docstringparser.py
===================================================================
--- trunk/epydoc/src/epydoc/docstringparser.py 2007-02-14 00:34:27 UTC (rev 1488)
+++ trunk/epydoc/src/epydoc/docstringparser.py 2007-02-14 01:20:09 UTC (rev 1489)
@@ -31,10 +31,12 @@
import re, sys
from epydoc import markup
+from epydoc.markup import epytext
from epydoc.apidoc import *
from epydoc.docintrospecter import introspect_docstring_lineno
from epydoc.util import py_src_filename
from epydoc import log
+import epydoc.docparser
import __builtin__, exceptions
######################################################################
@@ -69,7 +71,8 @@
added.
"""
def __init__(self, tags, label, plural=None,
- short=0, multivalue=1, takes_arg=0):
+ short=0, multivalue=1, takes_arg=0,
+ varnames=[]):
if type(tags) in (list, tuple):
self.tags = tuple(tags)
elif type(tags) is str:
@@ -81,6 +84,7 @@
self.multivalue = multivalue
self.short = short
self.takes_arg = takes_arg
+ self.varnames = varnames
def __cmp__(self, other):
if not isinstance(other, DocstringField): return -1
@@ -104,17 +108,21 @@
'Deprecated', multivalue=0),
# Status info
- DocstringField(['version'], 'Version', multivalue=0),
- DocstringField(['date'], 'Date', multivalue=0),
+ DocstringField(['version'], 'Version', multivalue=0,
+ varnames=['__version__']),
+ DocstringField(['date'], 'Date', multivalue=0,
+ varnames=['__date__']),
DocstringField(['status'], 'Status', multivalue=0),
# Bibliographic Info
- DocstringField(['author', 'authors'], 'Author', 'Authors', short=1),
+ DocstringField(['author', 'authors'], 'Author', 'Authors', short=1,
+ varnames=['__author__', '__authors__']),
DocstringField(['contact'], 'Contact', 'Contacts', short=1),
DocstringField(['organization', 'org'],
'Organization', 'Organizations'),
DocstringField(['copyright', '(c)'], 'Copyright', multivalue=0),
- DocstringField(['license'], 'License', multivalue=0),
+ DocstringField(['license'], 'License', multivalue=0,
+ varnames=['__license__']),
# Various warnings etc.
DocstringField(['bug'], 'Bug', 'Bugs'),
@@ -233,6 +241,11 @@
# some documented parameter.
check_type_fields(api_doc, field_warnings)
+ # Check for special variables (e.g., __version__)
+ if isinstance(api_doc, NamespaceDoc):
+ for field in STANDARD_FIELDS + user_docfields(api_doc, docindex):
+ add_metadata_from_var(api_doc, field)
+
# Extract a summary
if api_doc.summary is None and api_doc.descr is not None:
api_doc.summary, api_doc.other_docs = api_doc.descr.summary()
@@ -251,6 +264,33 @@
# Report any errors that occured
report_errors(api_doc, docindex, parse_errors, field_warnings)
+def add_metadata_from_var(api_doc, field):
+ if not field.multivalue:
+ for (f,a,d) in api_doc.metadata:
+ if field == f:
+ return # We already have a value for this metadata.
+ for varname in field.varnames:
+ # Check if api_doc has a variable w/ the given name.
+ if varname not in api_doc.variables: continue
+ if api_doc.variables[varname].value is UNKNOWN: continue
+ val_doc = api_doc.variables[varname].value
+ # Extract the value from the variable.
+ value = None
+ if val_doc.pyval is not UNKNOWN:
+ if isinstance(val_doc.pyval, basestring):
+ value = val_doc.pyval
+ elif val_doc.toktree is not UNKNOWN:
+ try: value = epydoc.docparser.parse_string(val_doc.toktree)
+ except KeyboardInterrupt: raise
+ except: pass
+ # If we found a value, then add it.
+ if value is not None:
+ if isinstance(value, str):
+ value = decode_with_backslashreplace(value)
+ value = epytext.ParsedEpytextDocstring(
+ epytext.parse_as_para(value))
+ api_doc.metadata.append( (field, varname, value) )
+
def initialize_api_doc(api_doc):
"""A helper function for L{parse_docstring()} that initializes
the attributes that C{parse_docstring()} will write to."""
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|