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)