Spaces:
Running
Running
| """Contains methods that generate documentation for Gradio functions and classes.""" | |
| from __future__ import annotations | |
| import inspect | |
| import warnings | |
| from collections import defaultdict | |
| from functools import lru_cache | |
| from typing import Callable | |
| classes_to_document = defaultdict(list) | |
| classes_inherit_documentation = {} | |
| def set_documentation_group(m): # noqa: ARG001 | |
| """A no-op for backwards compatibility of custom components published prior to 4.16.0""" | |
| pass | |
| 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 | |
| if i is None: | |
| raise NameError(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): | |
| if lines[j].startswith("self."): | |
| raise ValueError( | |
| 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 | |
| _module_prefixes = [ | |
| ("gradio._simple_templates", "component"), | |
| ("gradio.block", "block"), | |
| ("gradio.chat", "chatinterface"), | |
| ("gradio.component", "component"), | |
| ("gradio.events", "helpers"), | |
| ("gradio.exceptions", "helpers"), | |
| ("gradio.external", "helpers"), | |
| ("gradio.flag", "flagging"), | |
| ("gradio.helpers", "helpers"), | |
| ("gradio.interface", "interface"), | |
| ("gradio.layout", "layout"), | |
| ("gradio.route", "routes"), | |
| ("gradio.theme", "themes"), | |
| ("gradio_client.", "py-client"), | |
| ("gradio.utils", "helpers"), | |
| ] | |
| def _get_module_documentation_group(modname) -> str: | |
| for prefix, group in _module_prefixes: | |
| if modname.startswith(prefix): | |
| return group | |
| raise ValueError(f"No known documentation group for module {modname!r}") | |
| def document(*fns, inherit=False, documentation_group=None): | |
| """ | |
| 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. | |
| """ | |
| _documentation_group = documentation_group | |
| def inner_doc(cls): | |
| functions = list(fns) | |
| if hasattr(cls, "EVENTS"): | |
| functions += cls.EVENTS | |
| if inherit: | |
| classes_inherit_documentation[cls] = None | |
| documentation_group = _documentation_group # avoid `nonlocal` reassignment | |
| if _documentation_group is None: | |
| try: | |
| modname = inspect.getmodule(cls).__name__ # type: ignore | |
| if modname.startswith("gradio.") or modname.startswith( | |
| "gradio_client." | |
| ): | |
| documentation_group = _get_module_documentation_group(modname) | |
| else: | |
| # Then this is likely a custom Gradio component that we do not include in the documentation | |
| pass | |
| except Exception as exc: | |
| warnings.warn(f"Could not get documentation group for {cls}: {exc}") | |
| classes_to_document[documentation_group].append((cls, functions)) | |
| 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) | |
| if not (line.startswith(" ") or line.strip() == ""): | |
| raise SyntaxError( | |
| f"Documentation format for {fn.__name__} has format error in line: {line}" | |
| ) | |
| line = line[4:] | |
| if mode == "parameter": | |
| colon_index = line.index(": ") | |
| if colon_index < -1: | |
| raise SyntaxError( | |
| 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 == "self": | |
| 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 isinstance(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) | |
| if parameters: | |
| raise ValueError( | |
| f"Documentation format for {fn.__name__} documents " | |
| f"nonexistent parameters: {', '.join(parameters.keys())}. " | |
| f"Valid parameters: {', '.join(signature.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 | |
| elif mode == "description": | |
| description_lines.append(line if line.strip() else "<br>") | |
| else: | |
| if not (line.startswith(" ") or not line.strip()): | |
| raise SyntaxError( | |
| 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) | |
| if ( | |
| hasattr(cls, "preprocess") | |
| and callable(cls.preprocess) # type: ignore | |
| and hasattr(cls, "postprocess") | |
| and callable(cls.postprocess) # type: ignore | |
| ): | |
| preprocess_doc = document_fn(cls.preprocess, cls) # type: ignore | |
| postprocess_doc = document_fn(cls.postprocess, cls) # type: ignore | |
| preprocess_doc, postprocess_doc = ( | |
| { | |
| "parameter_doc": preprocess_doc[1], | |
| "return_doc": preprocess_doc[2], | |
| }, | |
| { | |
| "parameter_doc": postprocess_doc[1], | |
| "return_doc": postprocess_doc[2], | |
| }, | |
| ) | |
| 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": [], | |
| } | |
| if ( | |
| hasattr(cls, "preprocess") | |
| and callable(cls.preprocess) # type: ignore | |
| and hasattr(cls, "postprocess") | |
| and callable(cls.postprocess) # type: ignore | |
| ): | |
| cls_documentation["preprocess"] = preprocess_doc # type: ignore | |
| cls_documentation["postprocess"] = postprocess_doc # type: ignore | |
| 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) | |
| if fn_name in getattr(cls, "EVENTS", []): | |
| parameter_docs = parameter_docs[1:] | |
| 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: | |
| pass | |
| documentation[mode][i]["fns"].append(inherited_fn) | |
| return documentation | |