Home       Trees       Index       Help   

epydoc 3.0alpha2

Package epydoc :: Module docstringparser
[hide private]
[frames] | no frames]

Module docstringparser
source code

Parse docstrings and handle any fields it defines, such as @type and @author. Fields are used to describe specific information about an object. There are two classes of fields: simple fields and special fields.

Simple fields are fields that get stored directly in an APIDoc's metadata dictionary, without any special processing. The set of simple fields is defined by the list STANDARD_FIELDS, whose elements are DocstringFields.

Special fields are fields that perform some sort of processing on the APIDoc, or add information to attributes other than the metadata dictionary. Special fields are are handled by field handler functions, which are registered using register_field_handler.

Classes [hide private]
DocstringField A simple docstring field, which can be used to describe specific information about an object, such as its author or its version.

Functions [hide private]
    Docstring Parsing
  parse_docstring(api_doc, docindex)
Process the given APIDoc's docstring.
  initialize_api_doc(api_doc)
A helper function for parse_docstring() that initializes the attributes that parse_docstring() will write to.
  report_errors(api_doc, docindex, parse_errors, field_warnings)
A helper function for parse_docstring() that reports any markup warnings and field warnings that we encountered while processing api_doc's docstring.
    Field Processing
  process_field(api_doc, docindex, tag, arg, descr)
Process a single field, and use it to update api_doc.
  user_docfields(api_doc, docindex)
Return a list of user defined fields that can be used for the given object.
  register_field_handler(handler, *field_tags)
Register the given field handler function for processing any of the given field tags.
    Field Handler Functions
  process_summary_field(api_doc, docindex, tag, arg, descr)
Store descr in api_doc.summary
  process_include_field(api_doc, docindex, tag, arg, descr)
Copy the docstring contents from the object named in descr
  process_undocumented_field(api_doc, docindex, tag, arg, descr)
Remove any documentation for the variables named in descr
  process_group_field(api_doc, docindex, tag, arg, descr)
Define a group named arg containing the variables whose names are listed in descr.
  process_deffield_field(api_doc, docindex, tag, arg, descr)
Define a new custom field.
  process_raise_field(api_doc, docindex, tag, arg, descr)
Record the fact that api_doc can raise the exception named tag in api_doc.exception_descrs.
  process_sort_field(api_doc, docindex, tag, arg, descr)
  process_type_field(api_doc, docindex, tag, arg, descr)
  process_var_field(api_doc, docindex, tag, arg, descr)
  process_cvar_field(api_doc, docindex, tag, arg, descr)
  process_ivar_field(api_doc, docindex, tag, arg, descr)
  process_return_field(api_doc, docindex, tag, arg, descr)
  process_rtype_field(api_doc, docindex, tag, arg, descr)
  process_arg_field(api_doc, docindex, tag, arg, descr)
  process_kwarg_field(api_doc, docindex, tag, arg, descr)
    Helper Functions
  set_var_descr(api_doc, ident, descr)
  set_var_type(api_doc, ident, descr)
  _check(api_doc, tag, arg, context=None, expect_arg=None)
  get_docformat(api_doc, docindex)
Return the name of the markup language that should be used to parse the API documentation for the given object.
  unindent_docstring(docstring)
list of string _descr_to_identifiers(descr)
Given a ParsedDocstring that contains a list of identifiers, return a list of those identifiers.
  _descr_to_docstring_field(arg, descr)
    Function Signature Extraction
None parse_function_signature(func_doc)
Construct the signature for a builtin function or method from its docstring.

Variables [hide private]
STANDARD_FIELDS A list of the standard simple fields accepted by epydoc.
    Docstring Parsing
DEFAULT_DOCFORMAT The name of the default markup languge used to process docstrings.
    Field Processing Error Messages
UNEXPECTED_ARG  
EXPECTED_ARG  
EXPECTED_SINGLE_ARG  
BAD_CONTEXT  
REDEFINED  
UNKNOWN_TAG  
    Field Processing
_field_dispatch_table  
    Helper Functions
_IDENTIFIER_LIST_REGEXP  
    Function Signature Extraction
_SIGNATURE_RE A regular expression that is used to extract signatures from docstrings.

Function Details [hide private]

parse_docstring(api_doc, docindex)

source code 
call graph 
Process the given APIDoc's docstring. In particular, populate the APIDoc's descr and summary attributes, and add any information provided by fields in the docstring.
Parameters:
  • docindex - A DocIndex, used to find the containing module (to look up the docformat); and to find any user docfields defined by containing objects.

initialize_api_doc(api_doc)

source code 
call graph 
A helper function for parse_docstring() that initializes the attributes that parse_docstring() will write to.

report_errors(api_doc, docindex, parse_errors, field_warnings)

source code 
call graph 
A helper function for parse_docstring() that reports any markup warnings and field warnings that we encountered while processing api_doc's docstring.

process_field(api_doc, docindex, tag, arg, descr)

source code 
call graph 
Process a single field, and use it to update api_doc. If tag is the name of a special field, then call its handler function. If tag is the name of a simple field, then use process_simple_field to process it. Otherwise, check if it's a user-defined field, defined in this docstring or the docstring of a containing object; and if so, process it with process_simple_field.
Parameters:
  • tag - The field's tag, such as 'author'
  • arg - The field's optional argument
  • descr - The description following the field tag and argument.
Raises:
  • ValueError - If a problem was encountered while processing the field. The ValueError's string argument is an explanation of the problem, which should be displayed as a warning message.

user_docfields(api_doc, docindex)

source code 
call graph 
Return a list of user defined fields that can be used for the given object. This list is taken from the given api_doc, and any of its containing NamepaceDocs.

Bug: If a child's docstring is parsed before its parents, then its parent won't yet have had its extra_docstring_fields attribute initialized.

register_field_handler(handler, *field_tags)

source code 
Register the given field handler function for processing any of the given field tags. Field handler functions should have the following signature: 
>>> def field_handler(api_doc, docindex, tag, arg, descr):
...     '''update api_doc in response to the field.'''
Where api_doc is the documentation object to update; docindex is a DocIndex that can be used to look up the documentation for related objects; tag is the field tag that was used; arg is the optional argument; and descr is the description following the field tag and argument.

process_summary_field(api_doc, docindex, tag, arg, descr)

source code 
Store descr in api_doc.summary

process_include_field(api_doc, docindex, tag, arg, descr)

source code 
Copy the docstring contents from the object named in descr

process_undocumented_field(api_doc, docindex, tag, arg, descr)

source code 
Remove any documentation for the variables named in descr

process_group_field(api_doc, docindex, tag, arg, descr)

source code 
call graph 
Define a group named arg containing the variables whose names are listed in descr.

process_deffield_field(api_doc, docindex, tag, arg, descr)

source code 
call graph 
Define a new custom field.

process_raise_field(api_doc, docindex, tag, arg, descr)

source code 
call graph 
Record the fact that api_doc can raise the exception named tag in api_doc.exception_descrs.

process_sort_field(api_doc, docindex, tag, arg, descr)

source code 
call graph 

process_type_field(api_doc, docindex, tag, arg, descr)

source code 
call graph 

process_var_field(api_doc, docindex, tag, arg, descr)

source code 
call graph 

process_cvar_field(api_doc, docindex, tag, arg, descr)

source code 
call graph 

process_ivar_field(api_doc, docindex, tag, arg, descr)

source code 
call graph 

process_return_field(api_doc, docindex, tag, arg, descr)

source code 
call graph 

process_rtype_field(api_doc, docindex, tag, arg, descr)

source code 
call graph 

process_arg_field(api_doc, docindex, tag, arg, descr)

source code 
call graph 

process_kwarg_field(api_doc, docindex, tag, arg, descr)

source code 
call graph 

set_var_descr(api_doc, ident, descr)

source code 
call graph 

set_var_type(api_doc, ident, descr)

source code 
call graph 

_check(api_doc, tag, arg, context=None, expect_arg=None)

source code 
call graph 

get_docformat(api_doc, docindex)

source code 
call graph 
Return the name of the markup language that should be used to parse the API documentation for the given object.

unindent_docstring(docstring)

source code 
call graph 

_descr_to_identifiers(descr)

source code 
call graph 
Given a ParsedDocstring that contains a list of identifiers, return a list of those identifiers. This is used by fields such as @group and @sort, which expect lists of identifiers as their values. To extract the identifiers, the docstring is first converted to plaintext, and then split. The plaintext content of the docstring must be a a list of identifiers, separated by spaces, commas, colons, or semicolons.
Parameters:
Returns: list of string
A list of the identifier names contained in descr.
Raises:
  • ValueError - If descr does not contain a valid list of identifiers.

_descr_to_docstring_field(arg, descr)

source code 
call graph 

parse_function_signature(func_doc)

source code 
call graph 
Construct the signature for a builtin function or method from its docstring. If the docstring uses the standard convention of including a signature in the first line of the docstring (and formats that signature according to standard conventions), then it will be used to extract a signature. Otherwise, the signature will be set to a single varargs variable named "...".
Returns: None

Variables Details [hide private]

STANDARD_FIELDS

A list of the standard simple fields accepted by epydoc. This list can be augmented at run-time by a docstring with the special @deffield field. The order in which fields are listed here determines the order in which they will be displayed in the output.
Value:
[<Field: deprecated>,
 <Field: version>,
 <Field: date>,
 <Field: status>,
 <Field: author>,
 <Field: contact>,
 <Field: organization>,
 <Field: copyright>,
...

DEFAULT_DOCFORMAT

The name of the default markup languge used to process docstrings.
Value:
'plaintext'

UNEXPECTED_ARG

Value:
'%r did not expect an argument'

EXPECTED_ARG

Value:
'%r expected an argument'

EXPECTED_SINGLE_ARG

Value:
'%r expected a single argument'

BAD_CONTEXT

Value:
'Invalid context for %r'

REDEFINED

Value:
'Redefinition of %s'

UNKNOWN_TAG

Value:
'Unknown field tag %r'

_field_dispatch_table

Value:
{'arg': <function process_arg_field at 0x40251454>,
 'argument': <function process_arg_field at 0x40251454>,
 'cvar': <function process_cvar_field at 0x40251374>,
 'cvariable': <function process_cvar_field at 0x40251374>,
 'deffield': <function process_deffield_field at 0x4025125c>,
 'except': <function process_raise_field at 0x40251294>,
 'exception': <function process_raise_field at 0x40251294>,
 'group': <function process_group_field at 0x40251224>,
...

_IDENTIFIER_LIST_REGEXP

Value:
^[\w\.\*]+([\s,:;]\s*[\w\.\*]+)*$

_SIGNATURE_RE

A regular expression that is used to extract signatures from docstrings.
Value:
^\s*((\w+)\.)?(\w+)\(((\s*\[?\s*\*{,2}[\w-\.]+(=.+?)?(\s*\[?\s*,\s*\]?\
\s*\*{,2}[\w-\.]+(=.+?)?)*\]*)?)\s*\)(\s*(->)\s*(\S.*?))?\s*(\n|\s+(--\
|<=+>)\s+|$|\.\s+|\.\n)

   Home       Trees       Index       Help   

epydoc 3.0alpha2

Generated by Epydoc 3.0alpha2 on Tue Apr 11 17:31:11 2006 http://epydoc.sf.net