"""Contains methods that generate documentation for Gradio functions and classes."""
from __future__ import annotations
import inspect
from typing import Callable
classes_to_document = {}
classes_inherit_documentation = {}
documentation_group = None
def set_documentation_group(m):
global documentation_group
documentation_group = m
if m not in classes_to_document:
classes_to_document[m] = []
def extract_instance_attr_doc(cls, attr):
code = inspect.getsource(cls.__init__)
lines = [line.strip() for line in code.split("\n")]
i = None
for i, line in enumerate(lines): # noqa: B007
if line.startswith("self." + attr + ":") or line.startswith(
"self." + attr + " ="
):
break
assert i is not None, f"Could not find {attr} in {cls.__name__}"
start_line = lines.index('"""', i)
end_line = lines.index('"""', start_line + 1)
for j in range(i + 1, start_line):
assert not lines[j].startswith("self."), (
f"Found another attribute before docstring for {attr} in {cls.__name__}: "
+ lines[j]
+ "\n start:"
+ lines[i]
)
doc_string = " ".join(lines[start_line + 1 : end_line])
return doc_string
def document(*fns, inherit=False):
"""
Defines the @document decorator which adds classes or functions to the Gradio
documentation at www.gradio.app/docs.
Usage examples:
- Put @document() above a class to document the class and its constructor.
- Put @document("fn1", "fn2") above a class to also document methods fn1 and fn2.
- Put @document("*fn3") with an asterisk above a class to document the instance attribute methods f3.
"""
def inner_doc(cls):
global documentation_group
if inherit:
classes_inherit_documentation[cls] = None
classes_to_document[documentation_group].append((cls, fns))
return cls
return inner_doc
def document_fn(fn: Callable, cls) -> tuple[str, list[dict], dict, str | None]:
"""
Generates documentation for any function.
Parameters:
fn: Function to document
Returns:
description: General description of fn
parameters: A list of dicts for each parameter, storing data for the parameter name, annotation and doc
return: A dict storing data for the returned annotation and doc
example: Code for an example use of the fn
"""
doc_str = inspect.getdoc(fn) or ""
doc_lines = doc_str.split("\n")
signature = inspect.signature(fn)
description, parameters, returns, examples = [], {}, [], []
mode = "description"
for line in doc_lines:
line = line.rstrip()
if line == "Parameters:":
mode = "parameter"
elif line.startswith("Example:"):
mode = "example"
if "(" in line and ")" in line:
c = line.split("(")[1].split(")")[0]
if c != cls.__name__:
mode = "ignore"
elif line == "Returns:":
mode = "return"
else:
if mode == "description":
description.append(line if line.strip() else "<br>")
continue
if not (line.startswith(" ") or line.strip() == ""):
print(line)
assert (
line.startswith(" ") or line.strip() == ""
), f"Documentation format for {fn.__name__} has format error in line: {line}"
line = line[4:]
if mode == "parameter":
colon_index = line.index(": ")
assert (
colon_index > -1
), f"Documentation format for {fn.__name__} has format error in line: {line}"
parameter = line[:colon_index]
parameter_doc = line[colon_index + 2 :]
parameters[parameter] = parameter_doc
elif mode == "return":
returns.append(line)
elif mode == "example":
examples.append(line)
description_doc = " ".join(description)
parameter_docs = []
for param_name, param in signature.parameters.items():
if param_name.startswith("_"):
continue
if param_name in ["kwargs", "args"] and param_name not in parameters:
continue
parameter_doc = {
"name": param_name,
"annotation": param.annotation,
"doc": parameters.get(param_name),
}
if param_name in parameters:
del parameters[param_name]
if param.default != inspect.Parameter.empty:
default = param.default
if type(default) == str:
default = '"' + default + '"'
if default.__class__.__module__ != "builtins":
default = f"{default.__class__.__name__}()"
parameter_doc["default"] = default
elif parameter_doc["doc"] is not None:
if "kwargs" in parameter_doc["doc"]:
parameter_doc["kwargs"] = True
if "args" in parameter_doc["doc"]:
parameter_doc["args"] = True
parameter_docs.append(parameter_doc)
assert (
len(parameters) == 0
), f"Documentation format for {fn.__name__} documents nonexistent parameters: {''.join(parameters.keys())}"
if len(returns) == 0:
return_docs = {}
elif len(returns) == 1:
return_docs = {"annotation": signature.return_annotation, "doc": returns[0]}
else:
return_docs = {}
# raise ValueError("Does not support multiple returns yet.")
examples_doc = "\n".join(examples) if len(examples) > 0 else None
return description_doc, parameter_docs, return_docs, examples_doc
def document_cls(cls):
doc_str = inspect.getdoc(cls)
if doc_str is None:
return "", {}, ""
tags = {}
description_lines = []
mode = "description"
for line in doc_str.split("\n"):
line = line.rstrip()
if line.endswith(":") and " " not in line:
mode = line[:-1].lower()
tags[mode] = []
elif line.split(" ")[0].endswith(":") and not line.startswith(" "):
tag = line[: line.index(":")].lower()
value = line[line.index(":") + 2 :]
tags[tag] = value
else:
if mode == "description":
description_lines.append(line if line.strip() else "<br>")
else:
assert (
line.startswith(" ") or not line.strip()
), f"Documentation format for {cls.__name__} has format error in line: {line}"
tags[mode].append(line[4:])
if "example" in tags:
example = "\n".join(tags["example"])
del tags["example"]
else:
example = None
for key, val in tags.items():
if isinstance(val, list):
tags[key] = "<br>".join(val)
description = " ".join(description_lines).replace("\n", "<br>")
return description, tags, example
def generate_documentation():
documentation = {}
for mode, class_list in classes_to_document.items():
documentation[mode] = []
for cls, fns in class_list:
fn_to_document = cls if inspect.isfunction(cls) else cls.__init__
_, parameter_doc, return_doc, _ = document_fn(fn_to_document, cls)
cls_description, cls_tags, cls_example = document_cls(cls)
cls_documentation = {
"class": cls,
"name": cls.__name__,
"description": cls_description,
"tags": cls_tags,
"parameters": parameter_doc,
"returns": return_doc,
"example": cls_example,
"fns": [],
}
for fn_name in fns:
instance_attribute_fn = fn_name.startswith("*")
if instance_attribute_fn:
fn_name = fn_name[1:]
# Instance attribute fns are classes
# whose __call__ method determines their behavior
fn = getattr(cls(), fn_name).__call__
else:
fn = getattr(cls, fn_name)
if not callable(fn):
description_doc = str(fn)
parameter_docs = {}
return_docs = {}
examples_doc = ""
override_signature = f"gr.{cls.__name__}.{fn_name}"
else:
(
description_doc,
parameter_docs,
return_docs,
examples_doc,
) = document_fn(fn, cls)
override_signature = None
if instance_attribute_fn:
description_doc = extract_instance_attr_doc(cls, fn_name)
cls_documentation["fns"].append(
{
"fn": fn,
"name": fn_name,
"description": description_doc,
"tags": {},
"parameters": parameter_docs,
"returns": return_docs,
"example": examples_doc,
"override_signature": override_signature,
}
)
documentation[mode].append(cls_documentation)
if cls in classes_inherit_documentation:
classes_inherit_documentation[cls] = cls_documentation["fns"]
for mode, class_list in classes_to_document.items():
for i, (cls, _) in enumerate(class_list):
for super_class in classes_inherit_documentation:
if (
inspect.isclass(cls)
and issubclass(cls, super_class)
and cls != super_class
):
for inherited_fn in classes_inherit_documentation[super_class]:
inherited_fn = dict(inherited_fn)
try:
inherited_fn["description"] = extract_instance_attr_doc(
cls, inherited_fn["name"]
)
except (ValueError, AssertionError):
pass
documentation[mode][i]["fns"].append(inherited_fn)
return documentation