def get_object_api_doc(name_or_path):
"""returns the epydoc parse-only APIDoc object for the python file or object"""
if pathexists(name_or_path):
return parse_docs(filename=name_or_path)
else:
if valid_dotted_name(name_or_path):
return parse_docs(name=name_or_path)
raise IOError("No such file %s" % name_or_path)
def parse_type_decs(filename):
"""Scans through the contents of C{filename} to find lines which contain a
comment of the form '#: x : int' at the beginning (excluding whitespace) and
creates a list of L{ast_extensions.TypeDec} nodes.
TODO: This currently only handles single declarations like '#: x : int', but
we want it to also handle things like '#: x,y : int' and
'#: x : int, y : float'.
TODO: this will eventually have to be more sophisticated to handle better
integration with epydoc (ie, we shouldn't expect users to specify method
paramater types with variable docstrings; they should be able to use the
standard epydoc tag '@type'). This can be solved by either directly calling
epydoc at some point, but this seems mostly trivial and not worth forcing
clients of the applciation to install all 700 MB of the epydoc dependencies.
"""
tdecs = []
lineno = 0
p_debug("--- v Typedec parsing v ---")
for l in open(filename, 'r'):
# move to next line
lineno += 1
m = re.match(_TYPEDEC_REGEX, l)
p_debug(" tdec --> " + l[:-1], m)
p_debug(" " + l[:-1], not m)
if m:
var_name = m.group('id')
type_spec = m.group('t')
tdec = parse_type_dec(l, lineno, var_name, type_spec)
tdecs.append(tdec)
p_debug("--- ^ Typedec parsing ^ ---")
p_debug("--- v Function typedec parsing v ---")
d = docparser.parse_docs(filename)
for v in filter(lambda x: --IS X A FUNCTION VARIABLE?--, d.variables):
docstring = d.variables[v].value.docstring
# partypes is going to be a list of 2-tuples of parameter name and type
partypes = []
for line in filter(lambda x: re.match(r'\s*@type (.*): (.*)', x),
docstring.split('\n')):
groups = re.match(r'\s*@type (.*): (.*)', line).groups()
partypes.append((groups[0], groups[1]))
rtype_line = filter(lambda x: re.match(r'\s*@rtype: .*', x),
docstring.split('\n'))[0]
rtype = re.match(r'\s*@rtype: (.*)', rtype_line).groups()[0]
tdecs.append(make_function_tdec(partypes, rtype))
def runparser(s, attribs='', show=None, exclude=''):
"""
This test function takes a string containing the contents of a
module, and writes it to a file, uses `parse_docs` to parse it,
and pretty prints the resulting ModuleDoc object. The `attribs`
argument specifies which attributes of the `APIDoc`s should be
displayed. The `show` argument, if specifies, gives the name of
the object in the module that should be displayed (but the whole
module will always be inspected; this just selects what to
display).
"""
# Write it to a temp file.
tmp_dir = write_pystring_to_tmp_dir(s)
# Parse it.
val_doc = parse_docs(os.path.join(tmp_dir, 'epydoc_test.py'))
if show is not None:
for name in show.split('.'):
if isinstance(val_doc, ClassDoc):
val_doc = val_doc.local_variables[name].value
else:
val_doc = val_doc.variables[name].value
# Display it.
s = val_doc.pp(include=attribs.split(), exclude=exclude.split())
s = re.sub(r"filename = .*", "filename = ...", s)
print(s)
# Clean up.
cleanup_tmp_dir(tmp_dir)
def runparser(s, attribs='', show=None, exclude=''):
"""
This test function takes a string containing the contents of a
module, and writes it to a file, uses `parse_docs` to parse it,
and pretty prints the resulting ModuleDoc object. The `attribs`
argument specifies which attributes of the `APIDoc`s should be
displayed. The `show` argument, if specifies, gives the name of
the object in the module that should be displayed (but the whole
module will always be inspected; this just selects what to
display).
"""
# Write it to a temp file.
file_path = write_pystring_to_tmp_dir(s)
# Parse it.
val_doc = parse_docs(file_path)
if show is not None:
for name in show.split('.'):
if isinstance(val_doc, ClassDoc):
val_doc = val_doc.local_variables[name].value
else:
val_doc = val_doc.variables[name].value
# Display it.
s = val_doc.pp(include=attribs.split(), exclude=exclude.split())
s = re.sub(r"filename = .*", "filename = ...", s)
print(s)
# Clean up.
cleanup_tmp_dir(file_path)
def parse(filename=None, name=None):
d = docparser.parse_docs(filename, name)
isinstance(d, apidoc.APIDoc)
tokens = {}
print 'Imports:'
for imp in d.imports:
modName = str(imp)
outerContainer = modName.split('.')[-1]
tokens[modName] = docparser.parse_docs(name=modName)
tokens[outerContainer] = tokens[modName]
print tokens
print '\nVariables:'
vars = d.variables
for varName in vars:
print varName, vars[varName].docstring
if hasattr(vars[varName].value, 'parse_repr'):
print '\t', vars[varName].value.parse_repr
print '\t', vars[varName].value.docstring
def parse(filename=None, name=None):
d = docparser.parse_docs(filename, name)
isinstance(d, apidoc.APIDoc)
tokens = {}
print 'Imports:'
for imp in d.imports:
modName = str(imp)
outerContainer = modName.split('.')[-1]
tokens[modName] = docparser.parse_docs(name = modName)
tokens[outerContainer] = tokens[modName]
print tokens
print '\nVariables:'
vars=d.variables
for varName in vars:
print varName, vars[varName].docstring
if hasattr(vars[varName].value, 'parse_repr'):
print '\t', vars[varName].value.parse_repr
print '\t', vars[varName].value.docstring
def generate_api_docs():
logging.info('Generating api docs...')
from epydoc import docparser
try:
import roman
except ImportError:
print ("Could not import module 'roman,' docutils has not been installed"
"properly")
print "Please install docutils: http://docutils.sourceforge.net"
sys.exit(1)
from common import api
a = docparser.parse_docs(name='common.api')
variables = a.apidoc_links(imports=False,
packages=False,
submodules=False,
bases=False,
subclasses=False,
private=False,
overrides=False)
public_api_methods = api.PublicApi.methods.keys()
public_decorators = ['throttle', 'owner_required']
# allowed_names = public_api_methods + public_decorators
for v in variables:
if v.name in public_api_methods:
prefix = "method"
elif v.name in public_decorators:
prefix = "deco"
else:
continue
filename = '%s_%s.txt' % (prefix, v.name)
path = os.path.join(DOC_DIR, filename)
logging.info(' for %s...' % v.name)
docs = rst_docs(v.value)
f = open(path, 'w')
f.write(docs)
f.close()
logging.info('Finished generating api docs.')
def generate_api_docs():
logging.info('Generating api docs...')
from epydoc import docparser
try:
import roman
except ImportError:
print ("Could not import module 'roman,' docutils has not been installed"
"properly")
print "Please install docutils: http://docutils.sourceforge.net"
sys.exit(1)
from common import api
a = docparser.parse_docs(name='common.api')
variables = a.apidoc_links(imports=False,
packages=False,
submodules=False,
bases=False,
subclasses=False,
private=False,
overrides=False)
public_api_methods = api.PublicApi.methods.keys()
public_decorators = ['throttle', 'owner_required']
allowed_names = public_api_methods + public_decorators
for v in variables:
if v.name in public_api_methods:
prefix = "method"
elif v.name in public_decorators:
prefix = "deco"
else:
continue
filename = '%s_%s.txt' % (prefix, v.name)
path = os.path.join(DOC_DIR, filename)
logging.info(' for %s...' % v.name)
docs = rst_docs(v.value)
f = open(path, 'w')
f.write(docs)
f.close()
logging.info('Finished generating api docs.')
def getMethodTypedArgument(specFile):
val_doc = parse_docs(specFile)
doc = build_doc(specFile)
moduledoc = introspect_docs(filename=specFile)
methodDetails = dict()
for ckey in moduledoc.variables.iterkeys():
classdoc = moduledoc.variables[ckey].value
for rkey in classdoc.variables.iterkeys():
routinedoc = classdoc.variables[rkey].value
if isinstance(routinedoc, RoutineDoc):
argType=dict()
for arg in routinedoc.arg_types.iterkeys():
argument = str(routinedoc.arg_types[arg])
paramType = re.findall('<epytext><para inline=True>(?P<paramtype>.*)</para></epytext>', argument)[0]
argType[arg] = paramType
methodDetails[rkey] = argType
return methodDetails
def _get_docs_from_pyname(name, introspect, parse, progress_estimator,
supress_warnings=False):
progress_estimator.complete += 1
log.progress(progress_estimator.progress(), name)
introspect_doc = parse_doc = None
introspect_error = parse_error = None
if introspect:
try:
introspect_doc = introspect_docs(name=name)
except ImportError, e:
introspect_error = str(e)
if parse:
try:
parse_doc = parse_docs(name=name)
except ParseError, e:
parse_error = str(e)
except ImportError, e:
# If we get here, then there' probably no python source
# available; don't bother to generate a warnining.
pass
# Report any errors we encountered.
if not supress_warnings:
_report_errors(name, introspect_doc, parse_doc,
introspect_error, parse_error)
# Return the docs we found.
return (introspect_doc, parse_doc)
parse,
progress_estimator,
supress_warnings=False):
progress_estimator.complete += 1
log.progress(progress_estimator.progress(), name)
introspect_doc = parse_doc = None
introspect_error = parse_error = None
if introspect:
try:
introspect_doc = introspect_docs(name=name)
except ImportError, e:
introspect_error = str(e)
if parse:
try:
parse_doc = parse_docs(name=name)
except ParseError, e:
parse_error = str(e)
except ImportError, e:
# If we get here, then there' probably no python source
# available; don't bother to generate a warnining.
pass
# Report any errors we encountered.
if not supress_warnings:
_report_errors(name, introspect_doc, parse_doc, introspect_error,
parse_error)
# Return the docs we found.
return (introspect_doc, parse_doc)
