def helpNonVerbose(thing, title='Python Library Documentation: %s', forceload=0):
"""
Utility method to return python help in the form of a string
(based on the code in pydoc.py)
Note: only a string (including unicode) should be passed in for "thing"
"""
import pydoc as pydocs
import inspect
import string
result=""
# Important for converting an incoming c++ unicode character string!
thingStr=str(thing)
"""Display text documentation, given an object or a path to an object."""
try:
# Possible two-stage object resolution!
# Sometimes we get docs for strings, other times for objects
#
try:
object, name = pydocs.resolve(thingStr, forceload)
except:
# Get an object from a string
thingObj=eval(thingStr)
object, name = pydocs.resolve(thingObj, forceload)
desc = pydocs.describe(object)
module = inspect.getmodule(object)
if name and '.' in name:
desc += ' in ' + name[:name.rfind('.')]
elif module and module is not object:
desc += ' in module ' + module.__name__
if not (inspect.ismodule(object) or
inspect.isclass(object) or
inspect.isroutine(object) or
inspect.isgetsetdescriptor(object) or
inspect.ismemberdescriptor(object) or
isinstance(object, property)):
# If the passed object is a piece of data or an instance,
# document its available methods instead of its value.
object = type(object)
desc += ' object'
text = pydocs.TextDoc()
result=pydocs.plain(title % desc + '\n\n' + text.document(object, name))
# Remove multiple empty lines
result = [ line for line in result.splitlines() if line.strip() ]
result = string.join(result,"\n")
except:
pass
return result
def get_pydoc_completions(modulename=None):
"""Get possible completions for modulename for pydoc.
Returns a list of possible values to be passed to pydoc.
"""
modulename = compat.ensure_not_unicode(modulename)
modules = get_modules(modulename)
if modulename is None:
return modules
if modules is None:
modules = []
try:
module, name = resolve(modulename)
except:
return None
if isinstance(module, CONTAINER_TYPES):
modules.extend(name for name in dir(module)
if not name.startswith("_") and
isinstance(getattr(module, name),
PYDOC_TYPES))
if modules:
return modules
else:
return None
def getdoc(thing, title='Help on %s', forceload=0):
#g.trace(thing)
if 1: # Both seem to work.
# Redirect stdout to a "file like object".
old_stdout = sys.stdout
sys.stdout = fo = g.fileLikeObject()
# Python's builtin help function writes to stdout.
help(str(thing))
# Restore original stdout.
sys.stdout = old_stdout
# Return what was written to fo.
return fo.get()
else:
# Similar to doc function from pydoc module.
from pydoc import resolve, describe, inspect, text, plain
object, name = resolve(thing, forceload)
desc = describe(object)
module = inspect.getmodule(object)
if name and '.' in name:
desc += ' in ' + name[:name.rfind('.')]
elif module and module is not object:
desc += ' in module ' + module.__name__
doc = title % desc + '\n\n' + text.document(object, name)
return plain(doc)
def PrintHtml(name, things):
"""Print HTML documentation to stdout."""
ambiguous = len(things) > 1
content = ""
for thing in things:
obj, name = pydoc.resolve(thing, forceload=0)
title = pydoc.describe(obj)
if ambiguous:
if inspect.ismethoddescriptor(obj):
content += '\n\n<h2>method %s in class %s</h2>\n' % (obj.__name__, obj.__dict__)
else:
content += '<h2>%s in module <a href="py:%s">%s</a></h2>\n' % (title, obj.__module__, obj.__module__)
content += pydoc.html.document(obj, name)
if ambiguous:
title = 'Matches for "%s"' % name
content = '<h1>%s</h1>\n\n%s' % (title, content)
page = pydoc.html.page(title, content)
# Note: rewriting the anchors in a form more useful to Evergreen should be in Evergreen, not here.
# The rewriting here should be generally useful to anyone or anything that needs Python documentation.
# Remove a couple of useless (and seemingly broken) links.
page = page.replace('<a href=".">index</a><br>', '')
page = re.sub('<br><a href="[^"]+\.html">Module Docs</a>', '', page)
# There's a bug in pydoc that makes it output the text of the "Modules" section in cyan instead of white.
page = re.sub('"#fffff"', '"#ffffff"', page)
# The explicit font specifications are unnecessary manual uglification.
page = re.sub(' face="[^"]+"', '', page);
sys.stdout.write(page + '\n')
def test_url_resolves_to_post_like_toggle_view(self):
"""
VIEW_URL_NAME을 reverse한, 또는 VIEW_URL자체에 해당하는 view가 실제 views.post_like_toggle 뷰를 가리키는지 테스트
:return:
"""
found = resolve(self.VIEW_URL)
self.assertEqual(found.func, views.post_like_toggle)
def get_pydoc_completions(modulename=None):
"""Get possible completions for modulename for pydoc.
Returns a list of possible values to be passed to pydoc.
"""
modules = get_modules(modulename)
if modulename is None:
return modules
if modules is None:
modules = []
try:
module, name = resolve(modulename)
except:
return None
if isinstance(module, (type, types.ClassType,
types.ModuleType)):
modules.extend(name for name in dir(module)
if not name.startswith("_") and
isinstance(getattr(module, name),
(type,
types.FunctionType,
types.BuiltinFunctionType,
types.BuiltinMethodType,
types.ClassType,
types.MethodType,
types.ModuleType)))
if modules:
return modules
else:
return None
def doc2(thing, title="Python Library Documentation: %s", forceload=0):
"""Display text documentation, given an object or a path to an object."""
import types
try:
object, name = pydoc.resolve(thing, forceload)
desc = pydoc.describe(object)
module = mygetmodule(object)
if name and "." in name:
desc += " in " + name[: name.rfind(".")]
elif module and module is not object:
desc += " in module " + module.__name__
if not (
inspect.ismodule(object)
or inspect.isclass(object)
or inspect.isroutine(object)
or isinstance(object, property)
):
# If the passed object is a piece of data or an instance,
# document its available methods instead of its value.
# if this is a instance of used defined old-style class
if type(object) == types.InstanceType:
object = object.__class__
else:
object = type(object)
desc += " object"
pydoc.pager(title % desc + "\n\n" + pydoc.text.document(object, name))
except (ImportError, pydoc.ErrorDuringImport), value:
print value
def _writeclientdoc(doc, thing, forceload=0):
"""Write HTML documentation to a file in the current directory.
"""
docmodule = pydoc.HTMLDoc.docmodule
def strongarm(self, object, name=None, mod=None, *ignored):
result = docmodule(self, object, name, mod, *ignored)
# Grab all the aliases to pyclasses and create links.
nonmembers = []
push = nonmembers.append
for k,v in inspect.getmembers(object, inspect.isclass):
if inspect.getmodule(v) is not object and getattr(v,'typecode',None) is not None:
push('<a href="%s.html">%s</a>: pyclass alias<br/>' %(v.__name__,k))
result += self.bigsection('Aliases', '#ffffff', '#eeaa77', ''.join(nonmembers))
return result
pydoc.HTMLDoc.docmodule = strongarm
try:
object, name = pydoc.resolve(thing, forceload)
page = pydoc.html.page(pydoc.describe(object), pydoc.html.document(object, name))
name = os.path.join(doc, name + '.html')
file = open(name, 'w')
file.write(page)
file.close()
except (ImportError, pydoc.ErrorDuringImport), value:
log.debug(str(value))
def _writeclientdoc(doc, thing, forceload=0):
"""Write HTML documentation to a file in the current directory.
"""
docmodule = pydoc.HTMLDoc.docmodule
def strongarm(self, object, name=None, mod=None, *ignored):
result = docmodule(self, object, name, mod, *ignored)
# Grab all the aliases to pyclasses and create links.
nonmembers = []
push = nonmembers.append
for k,v in inspect.getmembers(object, inspect.isclass):
if inspect.getmodule(v) is not object and getattr(v,'typecode',None) is not None:
push('<a href="%s.html">%s</a>: pyclass alias<br/>' %(v.__name__,k))
result += self.bigsection('Aliases', '#ffffff', '#eeaa77', ''.join(nonmembers))
return result
pydoc.HTMLDoc.docmodule = strongarm
try:
object, name = pydoc.resolve(thing, forceload)
page = pydoc.html.page(pydoc.describe(object), pydoc.html.document(object, name))
name = os.path.join(doc, name + '.html')
file = open(name, 'w', 'utf-8')
file.write(page)
file.close()
except (ImportError, pydoc.ErrorDuringImport), value:
log.debug(str(value))
def gethtmldoc(thing, forceload=0):
obj, name = pydoc.resolve(thing, forceload)
page = pydoc.html.page(
pydoc.describe(obj),
pydoc.html.document(obj, name)
)
return page
def strongarm(self,
obj,
name=None,
mod=None,
funcs={},
classes={},
*ignored):
"""Produce HTML documentation for a class object."""
realname = obj.__name__
name = name or realname
bases = obj.__bases__
obj, name = pydoc.resolve(obj, forceload)
contents = []
push = contents.append
if name == realname:
title = '<a name="%s">class <strong>%s</strong></a>' % (name,
realname)
else:
title = '<strong>%s</strong> = <a name="%s">class %s</a>' % (
name, name, realname)
mdict = {}
if bases:
parents = []
for base in bases:
parents.append(self.classlink(base, obj.__module__))
title = title + '(%s)' % pydoc.join(parents, ', ')
doc = self.markup(pydoc.getdoc(obj), self.preformat, funcs, classes,
mdict)
doc = doc and '<tt>%s<br> </tt>' % doc
for iname, _ in cdict[name]:
fname = fdict[(name, iname)]
if iname in elements_dict:
push('class <a href="%s">%s</a>: element declaration typecode<br/>'\
%(fname,iname))
pyclass = elements_dict[iname]
if pyclass is not None:
push('<ul>instance attributes:')
push('<li><a href="%s">pyclass</a>: instances serializable to XML<br/></li>'\
%elements_dict[iname])
push('</ul>')
elif iname in types_dict:
push('class <a href="%s">%s</a>: type definition typecode<br/>'
% (fname, iname))
pyclass = types_dict[iname]
if pyclass is not None:
push('<ul>instance attributes:')
push('<li><a href="%s">pyclass</a>: instances serializable to XML<br/></li>'\
%types_dict[iname])
push('</ul>')
else:
push(
'class <a href="%s">%s</a>: TODO not sure what this is<br/>'
% (fname, iname))
contents = ''.join(contents)
return self.section(title, '#000000', '#ffc8d8', contents, 3, doc)
def getPydocHtml(oModule):
r"""Get pydoc for a module.
"""
sHtml = pydoc.html.document(*pydoc.resolve(thing=oModule))
sHtml = re.sub(r'<tr bgcolor="#aa55cc">.*?</td></tr></table></td></tr></table>', '</table>', sHtml, flags=re.DOTALL) # remove modules
sHtml = re.sub(r'<tr bgcolor="#55aa55">.*?</td></tr></table>', '</table>', sHtml, flags=re.DOTALL) # remove data
sHtml = re.sub(r'<a href=.*?</a>', '', sHtml) # remove links
return sHtml
def local_docs(word):
import pydoc
try:
obj, name = pydoc.resolve(word)
except ImportError:
return None
desc = pydoc.describe(obj)
return [(desc, urljoin(pydoc_url()[0], "%s.html" % word))]
def local_docs(word):
import pydoc
try:
obj, name = pydoc.resolve(word)
except ImportError:
return None
desc = pydoc.describe(obj)
return [(desc, urljoin(pydoc_url()[0], "%s.html" % word))]
def _writetypesdoc(doc, thing, forceload=0):
"""Write HTML documentation to a file in the current directory.
"""
try:
object, name = pydoc.resolve(thing, forceload)
name = os.path.join(doc, name + '.html')
except (ImportError, pydoc.ErrorDuringImport), value:
log.debug(str(value))
return
def _writetypesdoc(doc, thing, forceload=0):
"""Write HTML documentation to a file in the current directory.
"""
try:
object, name = pydoc.resolve(thing, forceload)
name = os.path.join(doc, name + '.html')
except (ImportError, pydoc.ErrorDuringImport), value:
log.debug(str(value))
return
def writedoc(thing):
"""Create HTML pages for `thing`"""
try:
obj, name = pydoc.resolve(thing)
p = page(pydoc.describe(obj), document(obj, name))
f = file(name+'.html', 'w')
f.write(p)
f.close()
print 'wrote', name+'.html'
except ImportError, e:
print e
def main():
document = ""
for clz in mrh.getAllDocumentedClasses():
object, name = pydoc.resolve(str(clz), 0)
document += pydoc.html.document(object, name)
page = create_page('MonkeyRunner API', document)
file = open(BASEDIR + 'monkeyrunner_api.html', 'w')
file.write(page)
file.close()
def custom_writedoc(thing, forceload=0):
"""Write HTML documentation to specific directory"""
try:
object, name = pydoc.resolve(thing, forceload)
page = pydoc.html.page(pydoc.describe(object), pydoc.html.document(object, name))
file = open(PYDOC_OUTPUT_DIR + name + '.html', 'w')
file.write(page)
file.close()
print 'wrote', PYDOC_OUTPUT_DIR + name + '.html'
except (ImportError, pydoc.ErrorDuringImport), value:
print value
def writeDocs(cls):
obj, name = pydoc.resolve(cls)
html = pydoc.html.page(pydoc.describe(obj), pydoc.html.document(obj, name))
markdown = html2text.html2text(html)
markdown = markdown.replace('`', '')
markdown = re.sub(r'^[ \t|]+', '', markdown, flags=re.MULTILINE)
rst = m2r.convert(markdown)
with open(os.path.join(apiDocsDir, f'{cls.__name__}.rst'), 'w') as file:
file.write(rst)
def _writedoc(doc, thing, forceload=0):
"""Write HTML documentation to a file in the current directory.
"""
try:
object, name = pydoc.resolve(thing, forceload)
page = pydoc.html.page(pydoc.describe(object), pydoc.html.document(object, name))
fname = os.path.join(doc, name + '.html')
file = open(fname, 'w', 'utf-8')
file.write(page)
file.close()
except (ImportError, pydoc.ErrorDuringImport), value:
traceback.print_exc(sys.stderr)
def test():
module = importfile("ext_doc.py")
tmp_obj, name = resolve(module)
print "GOT_C: ", find_class("foo", tmp_obj)
print "GOT_F: ", find_func("find_func", tmp_obj)
print "GOT_CF: ", find_func("foo:bar", tmp_obj)
print "GOT_RF: ", find_func("find_.*", tmp_obj, as_regexp=True)
print "GOT_CRF: \n", find_func("foo:.*", tmp_obj, as_regexp=True)
funcs = find_func("foo:.*", tmp_obj, as_regexp=True)
for f_name, f_ref in funcs:
dump_func_doc(f_name, f_ref)
dump_object(name, tmp_obj)
def _writedoc(doc, thing, forceload=0):
"""Write HTML documentation to a file in the current directory.
"""
try:
object, name = pydoc.resolve(thing, forceload)
page = pydoc.html.page(pydoc.describe(object), pydoc.html.document(object, name))
fname = os.path.join(doc, name + '.html')
file = open(fname, 'w')
file.write(page)
file.close()
except (ImportError, pydoc.ErrorDuringImport), value:
traceback.print_exc(sys.stderr)
def update_action(self, text):
o, n = pydoc.resolve(self.data, getattr(self.data, text))
self.ids.info_label.text = pydoc.text.document(o, n)
self.action = getattr(self.data, self.ids.action_choose.text)
self.ids.func_args.clear_widgets()
argspec = inspect.getargspec(self.action)
args, defs = argspec.args[1:], argspec.defaults
while len(defs) < len(args):
defs = [''] + defs
for i, a in enumerate(args):
entry = Factory.FormEntry(text=a, default=defs[i])
self.ids.func_args.add_widget(entry)
def get_completions(modulename):
modules = set("{0}.{1}".format(modulename, module)
for module in get_modules(modulename))
try:
module, name = resolve(modulename)
except ImportError:
return modules
if isinstance(module, CONTAINER_TYPES):
modules.update("{0}.{1}".format(modulename, name)
for name in dir(module) if not name.startswith("_")
and isinstance(getattr(module, name), PYDOC_TYPES))
return modules
def update_action(self, text):
o, n = pydoc.resolve(self.data, getattr(self.data, text))
self.ids.info_label.text = pydoc.text.document(o, n)
self.action = getattr(self.data, self.ids.action_choose.text)
self.ids.func_args.clear_widgets()
argspec = inspect.getargspec(self.action)
args, defs = argspec.args[1:], argspec.defaults
while len(defs) < len(args):
defs = [''] + defs
for i, a in enumerate(args):
entry = Factory.FormEntry(text=a,
default=defs[i])
self.ids.func_args.add_widget(entry)
def get_funcs(thing):
"""
return functions in python file
"""
funcs = []
_object, _ = pydoc.resolve(thing)
_all = getattr(_object, '__all__', None)
for key, value in inspect.getmembers(_object, inspect.isroutine):
if _all is not None or inspect.isbuiltin(
value) or inspect.getmodule(value) is _object:
if pydoc.visiblename(key, _all, _object):
funcs.append((key, value))
return funcs
def strongarm(self, object, name=None, mod=None, funcs={}, classes={}, *ignored):
"""Produce HTML documentation for a class object."""
realname = object.__name__
name = name or realname
bases = object.__bases__
object, name = pydoc.resolve(object, forceload)
contents = []
push = contents.append
if name == realname:
title = '<a name="%s">class <strong>%s</strong></a>' % (
name, realname)
else:
title = '<strong>%s</strong> = <a name="%s">class %s</a>' % (
name, name, realname)
mdict = {}
if bases:
parents = []
for base in bases:
parents.append(self.classlink(base, object.__module__))
title = title + '(%s)' % pydoc.join(parents, ', ')
doc = self.markup(pydoc.getdoc(object), self.preformat, funcs, classes, mdict)
doc = doc and '<tt>%s<br> </tt>' % doc
for iname,iclass in cdict[name]:
fname = fdict[(name,iname)]
if elements_dict.has_key(iname):
push('class <a href="%s">%s</a>: element declaration typecode<br/>'\
%(fname,iname))
pyclass = elements_dict[iname]
if pyclass is not None:
push('<ul>instance attributes:')
push('<li><a href="%s">pyclass</a>: instances serializable to XML<br/></li>'\
%elements_dict[iname])
push('</ul>')
elif types_dict.has_key(iname):
push('class <a href="%s">%s</a>: type definition typecode<br/>' %(fname,iname))
pyclass = types_dict[iname]
if pyclass is not None:
push('<ul>instance attributes:')
push('<li><a href="%s">pyclass</a>: instances serializable to XML<br/></li>'\
%types_dict[iname])
push('</ul>')
else:
push('class <a href="%s">%s</a>: TODO not sure what this is<br/>' %(fname,iname))
contents = ''.join(contents)
return self.section(title, '#000000', '#ffc8d8', contents, 3, doc)
def get_completions(modulename):
modules = set("{0}.{1}".format(modulename, module)
for module in get_modules(modulename))
try:
module, name = resolve(modulename)
except ImportError:
return modules
if isinstance(module, CONTAINER_TYPES):
modules.update("{0}.{1}".format(modulename, name)
for name in dir(module)
if not name.startswith("_") and
isinstance(getattr(module, name),
PYDOC_TYPES))
return modules
def buildAllDocs(symbol='pyroclast'): """Recursively constructs HTML pages of documentation the given module contents, beginning with pyroclast itself, which are subsequently written to the package's 'docs/' folder. """ dd = getDocDir() obj, name = pydoc.resolve(symbol) page = pydoc.html.page(pydoc.describe(obj), pydoc.html.document(obj,name)) with open(dd + name + '.html', 'w') as f: f.write(page) if hasattr(obj, '__all__'): for a in obj.__all__: identifier = name + '.' + a child = importlib.import_module(identifier) buildAllDocs(child)
def get_funcs(thing):
"""
Acquire functions in python file.
:param thing: python module.
:return: list(function name, function object), function name and corresponding function object
in python module.
"""
funcs = []
_object, _ = pydoc.resolve(thing)
_all = getattr(_object, '__all__', None)
for key, value in inspect.getmembers(_object, inspect.isroutine):
if _all is not None or inspect.isbuiltin(
value) or inspect.getmodule(value) is _object:
if pydoc.visiblename(key, _all, _object):
funcs.append((key, value))
return funcs
def buildAllDocs(symbol=name):
"""Recursively constructs HTML pages of documentation the given module
contents, beginning with the package itself, which are subsequently
written to the package's 'docs/' folder.
"""
dd = getDocDir()
obj, name = pydoc.resolve(symbol)
page = pydoc.html.page(pydoc.describe(obj), pydoc.html.document(obj, name))
print(name)
with open(dd + name + '.html', 'w') as f:
f.write(page)
if hasattr(obj, '__all__'):
for a in obj.__all__:
identifier = name + '.' + a
child = importlib.import_module(identifier)
buildAllDocs(child)
def get_funcs(module):
"""
Acquire functions in python file.
:param module: python module.
:return: dict
in python module.
"""
funcs = {}
_object, _ = pydoc.resolve(module)
_all = getattr(_object, '__all__', None)
for key, value in inspect.getmembers(_object, inspect.isroutine):
if _all is not None or inspect.isbuiltin(
value) or inspect.getmodule(value) is _object:
if pydoc.visiblename(key, _all, _object):
funcs[key] = value
return funcs
def render(thing, hlevel=1, forceload=0):
""" Render Markdown documentation, given an object or a path to an object. """
object, name = pydoc.resolve(thing, forceload)
if type(object) is pydoc._OLD_INSTANCE_TYPE:
# If the passed object is an instance of an old-style class,
# document its available methods instead of its value.
object = object.__class__
elif not (inspect.ismodule(object) or inspect.isclass(object) or
inspect.isroutine(object) or inspect.isgetsetdescriptor(object)
or inspect.ismemberdescriptor(object)
or isinstance(object, property)):
# If the passed object is a piece of data or an instance,
# document its available methods instead of its value.
object = type(object)
mddoc = MdDoc(hlevel=hlevel)
return mddoc.document(object, name)
def help(obj):
"""
Display HTML help for ``obj``, a Python object, module, etc. This
help is often more extensive than that given by 'obj?'. This
function does not return a value --- it prints HTML as a side
effect.
.. note::
This a wrapper around the built-in help. If formats the output
as HTML without word wrap, which looks better in the notebook.
INPUT:
- ``obj`` - a Python object, module, etc.
TESTS::
sage: import numpy.linalg
sage: current_dir = os.getcwd()
sage: os.chdir(tmp_dir('server_doctest'))
sage: sagenb.misc.support.help(numpy.linalg.norm)
<html><table notracebacks bgcolor="#386074" cellpadding=10 cellspacing=10><tr><td bgcolor="#f5f5f5"><font color="#37546d">
<a target='_new' href='cell://docs-....html'>Click to open help window</a>
<br></font></tr></td></table></html>
sage: os.chdir(current_dir)
"""
from pydoc import resolve, html, describe
import sagenb.notebook.interact as interact
print(
'<html><table notracebacks bgcolor="#386074" cellpadding=10 cellspacing=10><tr><td bgcolor="#f5f5f5"><font color="#37546d">'
)
object, name = resolve(obj)
page = html.page(describe(object), html.document(object, name))
page = page.replace('<a href', '<a ')
n = 0
while True:
filename = 'docs-%s.html' % n
if not os.path.exists(filename): break
n += 1
open(filename, 'w').write(page)
print(
" <a target='_new' href='cell://%s'>Click to open help window</a> "
% filename)
print('<br></font></tr></td></table></html>')
def create_deck(path, allow_special=False, allow_private=False, short=True):
"""
Create a "flashcard deck" of the target class or module's routines.
Construct an ordered mapping of routine names to docstrings for the target
class or module at `path`. Each routine name is complete with the routine's
signature.
Args:
obj (str): Dotted path to class or module.
allow_special (:obj:`bool`, optional): Allow __special__ routines. False by default.
allow_private (:obj:`bool`, optional): Allow _private routines. False by default.
short (:obj:`bool`, optional): Try to get only the synopsis line. True by default.
Returns:
tuple: (cards, quality)
Raises:
TypeError: If `path` resolves to anything other than a class or module.
ImportError: If no documentation can be found at `path`.
"""
logger.debug("Looking for documentation: `%s`", path)
cards = OrderedDict()
obj, _ = pydoc.resolve(path)
if not (inspect.isclass(obj) or inspect.ismodule(obj)):
raise TypeError("target must be class or module")
functions = inspect.getmembers(obj, inspect.isroutine)
# classes = inspect.getmembers(obj, inspect.isclass)
# functions += classes
n_eligible = 0
for name, func in functions:
if any((not allow_special and is_special(func), not allow_private
and is_private(func), is_deprecated(func))):
continue
sig, doc = get_doc(func, obj)
n_eligible += 1
if doc:
cards[f"{path}.{name}{sig}"] = shorten(doc) if short else doc
logger.debug("Finished looking for documentation.")
quality = (len(cards) / n_eligible) * 100
logger.debug("Found documentation for %i / %i (%i%%) eligible routines.",
len(cards), n_eligible, round(quality))
return cards, quality
def help(obj):
"""
Display HTML help for ``obj``, a Python object, module, etc. This
help is often more extensive than that given by 'obj?'. This
function does not return a value --- it prints HTML as a side
effect.
.. note::
This a wrapper around the built-in help. If formats the output
as HTML without word wrap, which looks better in the notebook.
INPUT:
- ``obj`` - a Python object, module, etc.
TESTS::
sage: import numpy.linalg
sage: import os, sage.misc.misc ; current_dir = os.getcwd()
sage: os.chdir(sage.misc.misc.tmp_dir('server_doctest'))
sage: sage.server.support.help(numpy.linalg.norm)
<html><table notracebacks bgcolor="#386074" cellpadding=10 cellspacing=10><tr><td bgcolor="#f5f5f5"><font color="#37546d">
<a target='_new' href='cell://docs-....html'>Click to open help window</a>
<br></font></tr></td></table></html>
sage: os.chdir(current_dir)
"""
from pydoc import resolve, html, describe
import sagenb.notebook.interact as interact
print '<html><table notracebacks bgcolor="#386074" cellpadding=10 cellspacing=10><tr><td bgcolor="#f5f5f5"><font color="#37546d">'
object, name = resolve(obj)
page = html.page(describe(object), html.document(object, name))
page = page.replace("<a href", "<a ")
n = 0
while True:
filename = "docs-%s.html" % n
if not os.path.exists(filename):
break
n += 1
open(filename, "w").write(page)
print " <a target='_new' href='cell://%s'>Click to open help window</a> " % filename
print "<br></font></tr></td></table></html>"
def document(resource, path):
print path
collections = []
for name in dir(resource):
if not "_" in name and callable(getattr(resource, name)) and hasattr(
getattr(resource, name), '__is_resource__'):
collections.append(name)
obj, name = pydoc.resolve(type(resource))
page = pydoc.html.page(
pydoc.describe(obj), pydoc.html.document(obj, name))
for name in collections:
page = re.sub('strong>(%s)<' % name, r'strong><a href="%s">\1</a><' % (path + name + ".html"), page)
for name in collections:
document(getattr(resource, name)(), path + name + ".")
f = open(os.path.join(BASE, path + 'html'), 'w')
f.write(page)
f.close()
def help(obj):
"""
Display help on s.
.. note::
This a wrapper around the builtin help. If formats the output
as HTML without word wrap, which looks better in the notebook.
INPUT:
- ``s`` - Python object, module, etc.
OUTPUT: prints out help about s; it's often more more extensive
than foo?
TESTS::
sage: import numpy.linalg
sage: sage.server.support.help(numpy.linalg.norm)
<html><table notracebacks bgcolor="#386074" cellpadding=10 cellspacing=10><tr><td bgcolor="#f5f5f5"><font color="#37546d">
<a target='_new' href='cell://docs-....html'>Click to open help window</a>
<br></font></tr></td></table></html>
"""
from pydoc import resolve, html, describe
import sage.server.notebook.interact as interact
print '<html><table notracebacks bgcolor="#386074" cellpadding=10 cellspacing=10><tr><td bgcolor="#f5f5f5"><font color="#37546d">'
object, name = resolve(obj)
page = html.page(describe(object), html.document(object, name))
page = page.replace('<a href','<a ')
n = 0
while True:
filename = 'docs-%s.html'%n
if not os.path.exists(filename): break
n += 1
open(filename, 'w').write(page)
print " <a target='_new' href='cell://%s'>Click to open help window</a> "%filename
print '<br></font></tr></td></table></html>'
def doc_asstring(thing, title='Python Library Documentation: %s', forceload=0):
"""return text documentation as a string, given an object or a path to an object."""
try:
object, name = pydoc.resolve(thing, forceload)
desc = pydoc.describe(object)
module = inspect.getmodule(object)
if name and '.' in name:
desc += ' in ' + name[:name.rfind('.')]
elif module and module is not object:
desc += ' in module ' + module.__name__
if not (inspect.ismodule(object) or inspect.isclass(object) or
inspect.isroutine(object) or inspect.isgetsetdescriptor(object)
or inspect.ismemberdescriptor(object)
or isinstance(object, property)):
# If the passed object is a piece of data or an instance,
# document its available methods instead of its value.
object = type(object)
desc += ' object'
return title % desc + '\n\n' + pydoc.text.document(object, name)
except (ImportError, ErrorDuringImport), value:
print value
def document(resource, path):
print path
collections = []
for name in dir(resource):
if not "_" in name and callable(getattr(resource, name)) and hasattr(
getattr(resource, name), '__is_resource__'):
collections.append(name)
obj, name = pydoc.resolve(type(resource))
page = pydoc.html.page(pydoc.describe(obj), pydoc.html.document(obj, name))
for name in collections:
page = re.sub('strong>(%s)<' % name,
r'strong><a href="%s">\1</a><' % (path + name + ".html"),
page)
for name in collections:
document(getattr(resource, name)(), path + name + ".")
f = open(os.path.join(BASE, path + 'html'), 'w')
f.write(page)
f.close()
def build(thing):
"""Build a dictionary mapping of a class."""
if 'django' in thing:
os.environ[
'DJANGO_SETTINGS_MODULE'] = 'classify.contrib.django.settings'
sys.path.insert(0, '')
klass = {
'attributes': DefaultOrderedDict(list),
'methods': DefaultOrderedDict(list),
'properties': [],
'ancestors': [],
'parents': [],
}
obj, name = pydoc.resolve(thing, forceload=0)
if type(obj) is pydoc._OLD_INSTANCE_TYPE:
# If the passed obj is an instance of an old-style class,
# dispatch its available methods instead of its value.
obj = obj.__class__
return classify(klass, obj, name)
def doc_asstring(thing, title='Python Library Documentation: %s', forceload=0):
"""return text documentation as a string, given an object or a path to an object."""
try:
object, name = pydoc.resolve(thing, forceload)
desc = pydoc.describe(object)
module = inspect.getmodule(object)
if name and '.' in name:
desc += ' in ' + name[:name.rfind('.')]
elif module and module is not object:
desc += ' in module ' + module.__name__
if not (inspect.ismodule(object) or
inspect.isclass(object) or
inspect.isroutine(object) or
inspect.isgetsetdescriptor(object) or
inspect.ismemberdescriptor(object) or
isinstance(object, property)):
# If the passed object is a piece of data or an instance,
# document its available methods instead of its value.
object = type(object)
desc += ' object'
return title % desc + '\n\n' + pydoc.text.document(object, name)
except (ImportError, ErrorDuringImport) as value:
print(value)
def main():
try:
opts, args = getopt.getopt(sys.argv[1:], '',
['test', 'module=', 'func=',
'class_doc=', 'module_doc',
'as_regexp=', 'func_template='])
except getopt.GetoptError:
usage(1)
as_regexp = True
for opt, val in opts:
if opt == '--help':
usage()
elif opt == '--test':
test()
elif opt == '--module':
module = importfile(val)
module_ref, module_name = resolve(module)
elif opt == '--as_regexp':
as_regexp = int(val)
elif opt == '--func':
funcs = find_func(val, module_ref, as_regexp=as_regexp)
for f_name, f_ref in funcs:
dump_func_doc(f_name, f_ref)
elif opt == '--class_doc':
class_ref = find_class(val, module_ref)
if not class_ref:
print "Unknown class: ", val
else:
doc = inspect.getdoc(class_ref) or inspect.getcomments(class_ref)
print doc
elif opt == '--module_doc':
print inspect.getdoc(module_ref)
elif opt == '--func_template':
global func_template
file = open(val, "r")
func_template = "".join(file.readlines())
def get_pydoc_completions(modulename=None):
"""Get possible completions for modulename for pydoc.
Returns a list of possible values to be passed to pydoc.
"""
modulename = compat.ensure_not_unicode(modulename)
modules = get_modules(modulename)
if modulename is None:
return modules
if modules is None:
modules = []
try:
module, name = resolve(modulename)
except:
return None
if isinstance(module, CONTAINER_TYPES):
modules.extend(name for name in dir(module) if not name.startswith("_")
and isinstance(getattr(module, name), PYDOC_TYPES))
if modules:
return modules
else:
return None
def helpNonVerbose(thing, title='Python Library Documentation: %s', forceload=0):
"""
Utility method to return python help in the form of a string
thing - str or unicode name to get help on
title - format string for help result
forceload - argument to pydoc.resolve, force object's module to be reloaded from file
returns formated help string
"""
result = ""
try:
thingStr = thing.encode(cmds.about(codeset=True))
except:
thingStr = str(thing)
try:
# Possible two-stage object resolution!
# Sometimes we get docs for strings, other times for objects
#
try:
object, name = pydoc.resolve(thingStr, forceload)
except:
# Get an object from a string
thingObj=eval(thingStr,sys.modules['__main__'].__dict__)
object, name = pydoc.resolve(thingObj, forceload)
desc = pydoc.describe(object)
module = inspect.getmodule(object)
if name and '.' in name:
desc += ' in ' + name[:name.rfind('.')]
elif module and module is not object:
desc += ' in module ' + module.__name__
doc = None
text = pydoc.TextDoc()
if not (inspect.ismodule(object) or
inspect.isclass(object) or
inspect.isroutine(object) or
inspect.isgetsetdescriptor(object) or
inspect.ismemberdescriptor(object) or
isinstance(object, property)):
# If the passed object is a piece of data or an instance,
# document its available methods instead of its value.
object = type(object)
desc += ' object'
# if the object is a maya command without a proper docstring,
# then tack on the help for it
elif module is cmds and inspect.isroutine(object):
try:
if len(object.__doc__) == 0:
doc = cmds.help(object.__name__)
except:
pass
if not doc:
doc = text.document(object, name)
result = pydoc.plain(title % desc + '\n\n' + doc)
# Remove multiple empty lines
result = "\n".join([ line for line in result.splitlines() if line.strip()])
except:
pass
return result
def render(resource):
obj, name = pydoc.resolve(type(resource))
return pydoc.html.page(
pydoc.describe(obj), pydoc.html.document(obj, name))
def _render(resource):
"""Use pydoc helpers on an instance to generate the help documentation.
"""
obj, name = pydoc.resolve(type(resource))
return pydoc.html.page(
pydoc.describe(obj), pydoc.html.document(obj, name))
import xbmc
MODULES = ('xbmc', 'xbmcplugin', 'xbmcgui', 'xbmcaddon', 'xbmcvfs')
if (__name__ == "__main__"):
Addon = xbmcaddon.Addon('script.pydoc-html-generator')
Dialog = xbmcgui.Dialog()
getString = Addon.getLocalizedString
if not Addon.getSetting('save_path'):
if Dialog.yesno(getString(30001), # choose folder
getString(30002), # Please choose a folder
getString(30005)): # Do you want to set now?
Addon.openSettings()
if Addon.getSetting('save_path'):
for module_name in MODULES:
try:
object, name = resolve(module_name, 0)
page = html.page(describe(object), html.document(object, name))
file_path = '%s/%s.html' % (Addon.getSetting('save_path'),
module_name)
file = open(xbmc.translatePath(file_path), 'w')
file.write(page)
file.close()
except:
xbmc.log('Unable to save doc for module "%s"' % module_name)
Dialog.ok(getString(30003), # Finish
getString(30004), # HTML pydoc's generated in
xbmc.translatePath(Addon.getSetting('save_path'))) # path
#!/usr/bin/python3
try:
from cStringIO import StringIO as BytesIO
except ImportError:
from io import BytesIO
import pydoc
import lxml.etree
html = pydoc.HTMLDoc()
# Generate the documentation from the pydoc strings
object, name = pydoc.resolve('pycdlib.pycdlib', 0)
page = html.page(pydoc.describe(object), html.document(object, name))
# Now parse that documentation
parser = lxml.etree.HTMLParser()
tree = lxml.etree.parse(BytesIO(page.encode('ascii')), parser)
# Now we remove the "Modules" section, since it contains only links to parts
# of the API that we are not documenting
doc = tree.getroot()
tables = doc.xpath('/html/body/table')
remove_table = None
for table in tables:
for tr in table.xpath('tr'):
bgcolor = tr.get('bgcolor')
if bgcolor == '#aa55cc':
# We found the 'Modules' section; go back up to the table to remove it
remove_table = table
def pydoc_html(name):
content = ''
ob, name = pydoc.resolve(name, 0)
text = MarkdownDoc()
content = text.document(ob, name)
return content
def docmodule(modname, root, force=False, usefile=False, dir=None):
name = modname
modulename = modname
if modname == '*':
if _gIsPy3:
modname = 'builtins'
else:
modname = '__builtin__'
if dir:
modinfo = imp.find_module(modname, [dir])
try:
obj = imp.load_module(modname, *modinfo)
except ImportError:
ex = sys.exc_info()[1]
cixfile = SubElement(root, "file",
lang="Python",
mtime=str(int(time.time())),
path=os.path.basename(modinfo[1]),
error=str(ex))
return
else:
# no dir is given, try to load from python path
try:
obj, modulename = pydoc.resolve(modname)
except Exception:
print(sys.exc_info()[1])
return
result = ''
try:
all = obj.__all__
except AttributeError:
all = None
try:
filename = inspect.getabsfile(obj)
except TypeError:
filename = '(built-in)'
if usefile:
cixfile = SubElement(root, "file",
lang="Python",
mtime=str(int(time.time())),
path=os.path.basename(filename))
else:
cixfile = root
module = obj
doc = getsdoc(obj) or None
moduleElt = SubElement(cixfile, "scope", ilk="blob", name=name, lang="Python")
if doc: moduleElt.set('doc', doc)
skips = module_skips.get(name, [])
callables = {}
for key, value in sorted(inspect.getmembers(obj)):
if key in skips:
continue
if inspect.ismodule(value):
process_module(moduleElt, value, key, callables, modname)
continue
if not visiblename(key): # forget about __all__
continue
if (inspect.isfunction(value) or
inspect.ismethod(value) or
inspect.ismethoddescriptor(value) or
inspect.isroutine(value) or
inspect.isbuiltin(value)):
process_routine(moduleElt, value, key, callables)
elif inspect.isclass(value) or (not _gIsPy3 and isinstance(value, types.TypeType)):
process_class(moduleElt, value, key, callables)
elif (_gIsPy3 and hasattr(value, 'class')) or (not _gIsPy3 and isinstance(value, types.InstanceType)):
klass = value.__class__
if klass.__module__ == name:
t = klass.__name__
else:
t = "%s.%s" % (klass.__module__, klass.__name__)
varElt = SubElement(moduleElt, "variable", name=key, citdl=t)
# make sure we also process the type of instances
process_class(moduleElt, klass, klass.__name__, callables)
elif isdata(value):
varElt = SubElement(moduleElt, "variable", name=key, citdl=type(value).__name__)
else:
log.warn("unexpected element in module '%s': '%s' is %r",
modulename, name, type(value))
helpername = os.path.join("helpers", modname + '_helper.py')
namespace = {}
if os.path.exists(helpername):
sys.stderr.write("Found helper module: %r\n" % helpername)
if _gIsPy3:
exec(compile(open(helpername).read(), os.path.basename(helpername), 'exec'), namespace, namespace)
else:
execfile(helpername, namespace, namespace)
# look in helpername for analyze_retval_exprs, which is a list of (callable_string, *args)
# and which corresponds to callables which when called w/ the specified args, will return
# variables which should be used to specify the <return> subelement of the callable.
analyze_retval_exprs = namespace.get('analyze_retval_exprs', [])
signatures = namespace.get('signatures', {})
for retval_expr in analyze_retval_exprs:
name, args = retval_expr
if name in callables:
callableElt = callables[name]
if name in signatures:
sig = signatures[name]
callableElt.set('signature', sig) # XXX???
playarea = module.__dict__
var = eval(name, playarea)(*args)
# find out what type that is
callableElt.set("returns", type(var).__name__)
else:
print("Don't know about: %r" % expr)
hidden_classes_exprs = namespace.get('hidden_classes_exprs', [])
for expr in hidden_classes_exprs:
playarea = module.__dict__
var = eval(expr, playarea)
name = type(var).__name__
process_class_using_instance(moduleElt, var, name, callables)
function_overrides = namespace.get('function_overrides')
if function_overrides is not None:
for name in function_overrides:
namesplit = name.split(".")
callableElt = callables[namesplit[0]]
for subname in namesplit[1:]:
for childElt in callableElt:
if childElt.get("name") == subname:
callableElt = childElt
break
else:
callableElt = None
break
if callableElt is None:
print(" couldn't find elem with name: %r" % (name, ))
continue
overrides = function_overrides[name]
for setting, value in overrides.items():
print(" overriding %s.%s %s attribute from %r to %r" % (modname, name, setting, callableElt.get(setting), value))
callableElt.set(setting, value)