def show_doc(elt,
doc_string: bool = True,
name=None,
title_level=None,
disp=True,
default_cls_level=2,
show_all_docments=False,
verbose=False):
"Show documentation for element `elt` with potential input documentation. Supported types: class, function, and enum."
elt = getattr(elt, '__func__', elt)
qname = name or qual_name(elt)
is_class = '.' in qname or inspect.isclass
if inspect.isclass(elt):
if is_enum(elt): name, args = _format_enum_doc(elt, qname)
else: name, args = _format_cls_doc(elt, qname)
elif callable(elt):
name, args = _format_func_doc(elt, qname, skip_params=('self', 'cls'))
else:
name, args = f"<code>{qname}</code>", ''
link = get_source_link(elt)
source_link = f'<a href="{link}" class="source_link" style="float:right">[source]</a>'
title_level = title_level or (default_cls_level
if inspect.isclass(elt) else 4)
doc = f'<h{title_level} id="{qname}" class="doc_header">{name}{source_link}</h{title_level}>'
doc += f'\n\n> {args}\n\n' if len(args) > 0 else '\n\n'
s = ''
try:
monospace = get_config().d.getboolean('monospace_docstrings', False)
except FileNotFoundError:
monospace = False
if doc_string and inspect.getdoc(elt):
s = inspect.getdoc(elt)
# doc links don't work inside markdown pre/code blocks
s = f'```\n{s}\n```' if monospace else add_doc_links(s, elt)
doc += s
if len(args) > 0:
if hasattr(elt, '__init__') and isclass(elt):
elt = elt.__init__
if is_source_available(elt):
if show_all_docments or _has_docment(elt):
if hasattr(elt, "__delwrap__"):
arg_dict, kwargs = _handle_delegates(elt)
doc += _get_docments(elt,
ment_dict=arg_dict,
with_return=True,
kwargs=kwargs,
monospace=monospace,
is_class=is_class)
else:
doc += _get_docments(elt,
monospace=monospace,
is_class=is_class)
elif verbose:
print(
f'Warning: `docments` annotations will not work for built-in modules, classes, functions, and `enums` and are unavailable for {qual_name(elt)}. They will not be shown'
)
if disp: display(Markdown(doc))
else: return doc
def show_doc(elt,
doc_string: bool = True,
name=None,
title_level=None,
disp=True,
default_cls_level=2,
show_all_docments=False,
verbose=False):
"Show documentation for element `elt` with potential input documentation. Supported types: class, function, and enum."
elt = getattr(elt, '__func__', elt)
qname = name or qual_name(elt)
if inspect.isclass(elt):
if is_enum(elt): name, args = _format_enum_doc(elt, qname)
else: name, args = _format_cls_doc(elt, qname)
elif callable(elt): name, args = _format_func_doc(elt, qname)
else: name, args = f"<code>{qname}</code>", ''
link = get_source_link(elt)
source_link = f'<a href="{link}" class="source_link" style="float:right">[source]</a>'
title_level = title_level or (default_cls_level
if inspect.isclass(elt) else 4)
doc = f'<h{title_level} id="{qname}" class="doc_header">{name}{source_link}</h{title_level}>'
doc += f'\n\n> {args}\n\n' if len(args) > 0 else '\n\n'
s = ''
if doc_string and inspect.getdoc(elt):
s = inspect.getdoc(elt)
# show_doc is used by doc so should not rely on Config
try:
monospace = (get_config().get('monospace_docstrings') == 'True')
except:
monospace = False
# doc links don't work inside markdown pre/code blocks
s = f'```\n{s}\n```' if monospace else add_doc_links(s, elt)
doc += s
if len(args) > 0:
if hasattr(elt, '__init__') and isclass(elt):
elt = elt.__init__
if is_source_available(elt):
if show_all_docments or _has_docment(elt):
s = f"\n\n{_format_args(elt)}"
if not monospace: s = add_doc_links(s)
doc += s
elif verbose:
print(
f'Warning: `docments` annotations will not work for built-in modules, classes, functions, and `enums` and are unavailable for {qual_name(elt)}. They will not be shown'
)
if disp: display(Markdown(doc))
else: return doc
def is_source_available(
elt, # A python object
):
"Checks if it is possible to return the source code of `elt` mimicking `inspect.getfile`"
if inspect.ismodule(elt):
return True if getattr(object, '__file__', None) else False
elif isclass(elt):
if hasattr(elt, '__module__'):
module = sys.modules.get(elt.__module__)
return True if getattr(module, '__file__', None) else False
elif getattr(elt, '__name__', None) == "<lambda>":
return False
elif inspect.ismethod(elt) or inspect.isfunction(elt) or inspect.istraceback(elt) or inspect.isframe(elt) or inspect.iscode(elt):
return True
elif is_enum(elt):
return False
return False
