def parse_docstring(api_doc, docindex):
"""
Process the given C{APIDoc}'s docstring. In particular, populate
the C{APIDoc}'s C{descr} and C{summary} attributes, and add any
information provided by fields in the docstring.
@param docindex: A DocIndex, used to find the containing
module (to look up the docformat); and to find any
user docfields defined by containing objects.
"""
if api_doc.metadata is not UNKNOWN:
log.debug("%s's docstring processed twice" % api_doc.canonical_name)
return
initialize_api_doc(api_doc)
# If there's no docstring, then there's nothing more to do.
if (api_doc.docstring in (None, UNKNOWN)):
return
# Remove leading indentation from the docstring.
api_doc.docstring = unindent_docstring(api_doc.docstring)
# Extract a signature from the docstring, if it has one. This
# overrides any signature we got via introspection/parsing.
if isinstance(api_doc, RoutineDoc):
parse_function_signature(api_doc)
# Parse the docstring. Any errors encountered are stored as
# `ParseError` objects in the errors list.
docformat = get_docformat(api_doc, docindex)
parse_errors = []
parsed_docstring = markup.parse(api_doc.docstring, docformat,
parse_errors)
# Divide the docstring into a description and a list of
# fields.
descr, fields = parsed_docstring.split_fields(parse_errors)
api_doc.descr = descr
# Process fields
field_warnings = []
for field in fields:
try:
process_field(api_doc, docindex, field.tag(),
field.arg(), field.body())
except ValueError, e: field_warnings.append(str(e))
# Extract a summary
if api_doc.summary is None and api_doc.descr is not None:
api_doc.summary = api_doc.descr.summary()
# [XX] Make sure we don't have types/param descrs for unknown
# vars/params?
# Report any errors that occured
report_errors(api_doc, docindex, parse_errors, field_warnings)
def parse_docstring(api_doc, docindex, suppress_warnings=[]):
"""
Process the given C{APIDoc}'s docstring. In particular, populate
the C{APIDoc}'s C{descr} and C{summary} attributes, and add any
information provided by fields in the docstring.
@param docindex: A DocIndex, used to find the containing
module (to look up the docformat); and to find any
user docfields defined by containing objects.
@param suppress_warnings: A set of objects for which docstring
warnings should be suppressed.
"""
if api_doc.metadata is not UNKNOWN:
if not (isinstance(api_doc, RoutineDoc)
and api_doc.canonical_name[-1] == '__init__'):
log.debug("%s's docstring processed twice" %
api_doc.canonical_name)
return
initialize_api_doc(api_doc)
# If there's no docstring, then check for special variables (e.g.,
# __version__), and then return -- there's nothing else to do.
if (api_doc.docstring in (None, UNKNOWN)):
if isinstance(api_doc, NamespaceDoc):
for field in STANDARD_FIELDS + user_docfields(api_doc, docindex):
add_metadata_from_var(api_doc, field)
return
# Remove leading indentation from the docstring.
api_doc.docstring = unindent_docstring(api_doc.docstring)
# Decide which docformat is used by this module.
docformat = get_docformat(api_doc, docindex)
# A list of markup errors from parsing.
parse_errors = []
# Extract a signature from the docstring, if it has one. This
# overrides any signature we got via introspection/parsing.
if isinstance(api_doc, RoutineDoc):
parse_function_signature(api_doc, None, docformat, parse_errors)
# Parse the docstring. Any errors encountered are stored as
# `ParseError` objects in the errors list.
parsed_docstring = markup.parse(api_doc.docstring, docformat, parse_errors)
# Divide the docstring into a description and a list of
# fields.
descr, fields = parsed_docstring.split_fields(parse_errors)
api_doc.descr = descr
field_warnings = []
# Handle the constructor fields that have been defined in the class
# docstring. This code assumes that a class docstring is parsed before
# the same class __init__ docstring.
if isinstance(api_doc, ClassDoc):
# Parse ahead the __init__ docstring for this class
initvar = api_doc.variables.get('__init__')
if initvar and isinstance(initvar.value, RoutineDoc):
init_api_doc = initvar.value
parse_docstring(init_api_doc, docindex, suppress_warnings)
parse_function_signature(init_api_doc, api_doc, docformat,
parse_errors)
init_fields = split_init_fields(fields, field_warnings)
# Process fields
for field in init_fields:
try:
process_field(init_api_doc, docindex, field.tag(),
field.arg(), field.body())
except ValueError as e:
field_warnings.append(str(e))
# Process fields
for field in fields:
try:
process_field(api_doc, docindex, field.tag(), field.arg(),
field.body())
except ValueError as e:
field_warnings.append(str(e))
# Check to make sure that all type parameters correspond to
# some documented parameter.
check_type_fields(api_doc, field_warnings)
# 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()
# If the summary is empty, but the return field is not, then use
# the return field to generate a summary description.
if (isinstance(api_doc, RoutineDoc) and api_doc.summary is None
and api_doc.return_descr is not None):
s, o = api_doc.return_descr.summary()
api_doc.summary = RETURN_PDS + s
api_doc.other_docs = o
# [XX] Make sure we don't have types/param descrs for unknown
# vars/params?
# Report any errors that occured
if api_doc in suppress_warnings:
if parse_errors or field_warnings:
log.info("Suppressing docstring warnings for %s, since it "
"is not included in the documented set." %
api_doc.canonical_name)
else:
report_errors(api_doc, docindex, parse_errors, field_warnings)
def parse_docstring(api_doc, docindex, suppress_warnings=[]):
"""
Process the given C{APIDoc}'s docstring. In particular, populate
the C{APIDoc}'s C{descr} and C{summary} attributes, and add any
information provided by fields in the docstring.
@param docindex: A DocIndex, used to find the containing
module (to look up the docformat); and to find any
user docfields defined by containing objects.
@param suppress_warnings: A set of objects for which docstring
warnings should be suppressed.
"""
if api_doc.metadata is not UNKNOWN:
if not (isinstance(api_doc, RoutineDoc)
and api_doc.canonical_name[-1] == '__init__'):
log.debug("%s's docstring processed twice" %
api_doc.canonical_name)
return
initialize_api_doc(api_doc)
# If there's no docstring, then check for special variables (e.g.,
# __version__), and then return -- there's nothing else to do.
if (api_doc.docstring in (None, UNKNOWN)):
if isinstance(api_doc, NamespaceDoc):
for field in STANDARD_FIELDS + user_docfields(api_doc, docindex):
add_metadata_from_var(api_doc, field)
return
# Remove leading indentation from the docstring.
api_doc.docstring = unindent_docstring(api_doc.docstring)
# Decide which docformat is used by this module.
docformat = get_docformat(api_doc, docindex)
# A list of markup errors from parsing.
parse_errors = []
# Extract a signature from the docstring, if it has one. This
# overrides any signature we got via introspection/parsing.
if isinstance(api_doc, RoutineDoc):
parse_function_signature(api_doc, None, docformat, parse_errors)
# Parse the docstring. Any errors encountered are stored as
# `ParseError` objects in the errors list.
parsed_docstring = markup.parse(api_doc.docstring, docformat,
parse_errors)
# Divide the docstring into a description and a list of
# fields.
descr, fields = parsed_docstring.split_fields(parse_errors)
api_doc.descr = descr
field_warnings = []
# Handle the constructor fields that have been defined in the class
# docstring. This code assumes that a class docstring is parsed before
# the same class __init__ docstring.
if isinstance(api_doc, ClassDoc):
# Parse ahead the __init__ docstring for this class
initvar = api_doc.variables.get('__init__')
if initvar and isinstance(initvar.value, RoutineDoc):
init_api_doc = initvar.value
parse_docstring(init_api_doc, docindex, suppress_warnings)
parse_function_signature(init_api_doc, api_doc,
docformat, parse_errors)
init_fields = split_init_fields(fields, field_warnings)
# Process fields
for field in init_fields:
try:
process_field(init_api_doc, docindex, field.tag(),
field.arg(), field.body())
except ValueError, e: field_warnings.append(str(e))
# Process fields
for field in fields:
try:
process_field(api_doc, docindex, field.tag(),
field.arg(), field.body())
except ValueError, e: field_warnings.append(str(e))
# Check to make sure that all type parameters correspond to
# some documented parameter.
check_type_fields(api_doc, field_warnings)
# 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()
# If the summary is empty, but the return field is not, then use
# the return field to generate a summary description.
if (isinstance(api_doc, RoutineDoc) and api_doc.summary is None and
api_doc.return_descr is not None):
s, o = api_doc.return_descr.summary()
api_doc.summary = RETURN_PDS + s
api_doc.other_docs = o
# [XX] Make sure we don't have types/param descrs for unknown
# vars/params?
# Report any errors that occured
if api_doc in suppress_warnings:
if parse_errors or field_warnings:
log.info("Suppressing docstring warnings for %s, since it "
"is not included in the documented set." %
api_doc.canonical_name)
else:
report_errors(api_doc, docindex, parse_errors, field_warnings)
def parse_docstring(api_doc, docindex):
"""
Process the given C{APIDoc}'s docstring. In particular, populate
the C{APIDoc}'s C{descr} and C{summary} attributes, and add any
information provided by fields in the docstring.
@param docindex: A DocIndex, used to find the containing
module (to look up the docformat); and to find any
user docfields defined by containing objects.
"""
if api_doc.metadata is not UNKNOWN:
if not (isinstance(api_doc, RoutineDoc)
and api_doc.canonical_name[-1] == '__init__'):
log.debug("%s's docstring processed twice" %
api_doc.canonical_name)
return
initialize_api_doc(api_doc)
# If there's no docstring, then there's nothing more to do.
if (api_doc.docstring in (None, UNKNOWN)):
return
# Remove leading indentation from the docstring.
api_doc.docstring = unindent_docstring(api_doc.docstring)
# Extract a signature from the docstring, if it has one. This
# overrides any signature we got via introspection/parsing.
if isinstance(api_doc, RoutineDoc):
parse_function_signature(api_doc)
# Parse the docstring. Any errors encountered are stored as
# `ParseError` objects in the errors list.
docformat = get_docformat(api_doc, docindex)
parse_errors = []
parsed_docstring = markup.parse(api_doc.docstring, docformat, parse_errors)
# Divide the docstring into a description and a list of
# fields.
descr, fields = parsed_docstring.split_fields(parse_errors)
api_doc.descr = descr
field_warnings = []
# Handle the constructor fields that have been defined in the class
# docstring. This code assumes that a class docstring is parsed before
# the same class __init__ docstring.
if isinstance(api_doc, ClassDoc):
# Parse ahead the __init__ docstring for this class
initvar = api_doc.variables.get('__init__')
if initvar and initvar.value not in (None, UNKNOWN):
init_api_doc = initvar.value
parse_docstring(init_api_doc, docindex)
parse_function_signature(init_api_doc, api_doc)
init_fields = split_init_fields(fields, field_warnings)
# Process fields
for field in init_fields:
try:
process_field(init_api_doc, docindex, field.tag(),
field.arg(), field.body())
except ValueError, e:
field_warnings.append(str(e))
