| """Contains methods that generate documentation for Gradio functions and classes.""" |
|
|
| from __future__ import annotations |
|
|
| import inspect |
| from typing import Callable, Dict, List, Tuple |
|
|
| classes_to_document = {} |
| 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 document(*fns): |
| """ |
| 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 the class methods fn1 and fn2. |
| """ |
|
|
| def inner_doc(cls): |
| global documentation_group |
| classes_to_document[documentation_group].append((cls, fns)) |
| return cls |
|
|
| return inner_doc |
|
|
|
|
| def document_fn(fn: Callable) -> 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 == "Example:": |
| mode = "example" |
| elif line == "Returns:": |
| mode = "return" |
| else: |
| if mode == "description": |
| description.append(line if line.strip() else "<br>") |
| continue |
| 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 == "kwargs" 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 and "kwargs" in parameter_doc["doc"]: |
| parameter_doc["kwargs"] = 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 = {} |
| |
| 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_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: |
| fn = getattr(cls, fn_name) |
| ( |
| description_doc, |
| parameter_docs, |
| return_docs, |
| examples_doc, |
| ) = document_fn(fn) |
| cls_documentation["fns"].append( |
| { |
| "fn": fn, |
| "name": fn_name, |
| "description": description_doc, |
| "tags": {}, |
| "parameters": parameter_docs, |
| "returns": return_docs, |
| "example": examples_doc, |
| } |
| ) |
| documentation[mode].append(cls_documentation) |
| return documentation |
|
|
