文档化自定义组件

在 4.15 版本中，我们向 Gradio CLI 添加了一个新的 gradio cc docs 命令，用于为您的自定义组件生成丰富的文档。此命令将自动为用户生成文档，但要充分利用它，您需要做一些事情。

如何使用？

文档将在运行 gradio cc build 时生成。您可以传递 --no-generate-docs 参数来关闭此行为。

还有一个独立的 docs 命令，可以进行更高级的自定义。如果您手动运行此命令，它应该在 pyproject.toml 中的 version 版本号更新之后但在构建组件之前运行。

所有参数都是可选的。

gradio cc docs
  path # The directory of the custom component.
  --demo-dir # Path to the demo directory.
  --demo-name # Name of the demo file
  --space-url # URL of the Hugging Face Space to link to
  --generate-space # create a documentation space.
  --no-generate-space # do not create a documentation space
  --readme-path # Path to the README.md file.
  --generate-readme # create a REAMDE.md file
  --no-generate-readme # do not create a README.md file
  --suppress-demo-check # suppress validation checks and warnings

生成了什么？

gradio cc docs 命令将生成一个交互式 Gradio 应用程序和一个静态的 README 文件，其中包含各种功能。您可以在此查看示例

• 部署在 Hugging Face Spaces 上的 Gradio 应用程序
• 由 GitHub 渲染的 README.md

README.md 和 Spaces 都具有以下功能

• 描述。
• 安装说明。
• 一个完全可用的代码片段。
• 可选地链接到 PyPi、GitHub 和 Hugging Face Spaces。
• API 文档，包括
  • 组件初始化参数表，显示类型、默认值和描述。
  • 组件如何影响用户预测函数的描述。
  • 事件及其描述的表格。
  • 初始化或预处理/后处理中可能使用的任何附加接口或类。

此外，Gradio 还包括

• 实时演示。
• 更丰富、交互式的参数表。
• 更漂亮的样式！

我需要做什么？

文档生成器使用现有标准来提取必要信息，即类型提示（Type Hints）和文档字符串（Docstrings）。没有 Gradio 特定的文档 API，因此遵循最佳实践通常会产生最佳结果。

如果您的组件源代码中已经使用了类型提示和文档字符串，那么您无需做太多即可从该功能中受益，但您应该注意一些细节。

Python 版本

为了获得最佳的文档体验，生成文档时需要使用 Python 3.10 或更高版本。这是因为一些用于生成文档的内省功能仅在 3.10 中添加。

类型提示

Python 类型提示被广泛用于为用户提供有用的信息。

我需要为哪些部分添加类型提示？

您无需为代码的每个部分都添加类型提示。为了使文档正常工作，您需要为以下组件方法添加类型提示：

• __init__ 参数应该有类型。
• postprocess 参数和返回值应该有类型。
• preprocess 参数和返回值应该有类型。

如果您使用 gradio cc create 克隆了一个模板，这些类型应该已经存在，但您可能需要根据您所做的任何更改进行调整。

__init__

这里，您只需要为参数添加类型。如果您使用 gradio cc create 克隆了模板，这些参数应该已经就位。您只需为添加或更改的任何内容添加新的类型提示即可。

def __init__(
  self,
  value: str | None = None,
  *,
  sources: Literal["upload", "microphone"] = "upload,
  every: Timer | float | None = None,
  ...
):
  ...

preprocess 和 postprocess

preprocess 和 postprocess 方法决定了传递给用户函数的值以及需要返回的值。

即使您的组件设计主要作为输入或输出，也值得为输入参数和返回值添加类型提示，因为 Gradio 无法限制组件的使用方式。

在这种情况下，我们特别关注：

• preprocess 的返回类型。
• postprocess 的输入类型。

def preprocess(
  self, payload: FileData | None # input is optional
) -> tuple[int, str] | str | None:

# user function input  is the preprocess return ▲
# user function output is the postprocess input ▼

def postprocess(
  self, value: tuple[int, str] | None
) -> FileData | bytes | None: # return is optional
  ...

Docstrings

文档字符串也广泛用于提取 API 特定部分的更有意义、更易读的描述。

虽然文档字符串没有任何语法要求，但为了文档目的，我们需要一个特定的结构。

与类型提示一样，我们关注的具体信息如下：

• __init__ 参数文档字符串。
• preprocess 返回值文档字符串。
• postprocess 输入参数文档字符串。

其他所有都是可选的。

文档字符串应始终采用此格式才能被文档生成器识别：

类

"""
A description of the class.

This can span multiple lines and can _contain_ *markdown*.
"""

方法和函数

这些描述中的 Markdown 将不会转换为格式化文本。

"""
Parameters:
    param_one: A description for this parameter.
    param_two: A description for this parameter.
Returns:
    A description for this return value.
"""

事件

在自定义组件中，事件表示为存储在组件类 events 字段上的列表。虽然事件不需要类型，但我们确实需要人类可读的描述，以便用户了解事件的行为。

为方便起见，我们必须以特定方式创建事件。

有两种方法可以向自定义组件添加事件。

内置事件

Gradio 附带各种内置事件，可能足以满足您的组件需求。如果您使用内置事件，则无需执行任何操作，因为它们已经包含我们可以提取的描述。

from gradio.events import Events

class ParamViewer(Component):
  ...

  EVENTS = [
    Events.change,
    Events.upload,
  ]

自定义事件

如果内置事件不适用于您的用例，您可以定义自定义事件。这是一个简单的过程，但您必须以这种方式创建事件，以便文档字符串正常工作。

from gradio.events import Events, EventListener

class ParamViewer(Component):
  ...

  EVENTS = [
    Events.change,
    EventListener(
        "bingbong",
        doc="This listener is triggered when the user does a bingbong."
      )
  ]

演示

通常用于开发组件的 demo/app.py 用于生成实时演示和代码片段。这里唯一严格的规则是 demo.launch() 命令必须包含在 __name__ == "__main__" 条件语句中，如下所示：

if __name__ == "__main__":
  demo.launch()

文档生成器将扫描此类子句，如果缺少则会报错。如果您不在 demo/app.py 中启动演示，则可以传递 --suppress-demo-check 来关闭此检查。

演示建议

虽然没有额外的规则，但您应该牢记一些最佳实践，以获得文档生成器的最佳体验。

这些只是指导原则，每个情况都是独一无二的，但它们是值得记住的可靠原则。

保持演示简洁

简洁的演示看起来更好，也更容易让用户理解演示的功能。尽量移除所有无关的 UI 元素，将用户的注意力集中在核心用例上。

有时，为文档单独创建一个 demo/app.py，而为测试目的创建另一个更复杂的应用程序可能更有意义。您还可以创建其他 Space，展示更复杂的示例，并从主类文档字符串或 pyproject.toml 描述中链接到它们。

保持代码简洁

“快速入门”片段利用了演示代码，该代码应尽可能短，以保持用户参与并避免混淆。

示例片段的任务不是演示整个 API；此片段应是新用户成功的捷径。它应该易于输入或复制粘贴，并且易于理解。解释性注释应简洁明了。

避免外部依赖

如上所述，用户应该能够复制粘贴片段并获得一个完全可用的应用程序。尽量避免第三方库依赖，以便于此。

您应该仔细考虑任何示例；避免需要额外文件或对环境做出假设的示例通常是一个好主意。

确保 demo 目录是独立的

在某些情况下，只有 demo 目录会被上传到 Hugging Face Spaces，因为组件如果可能的话会通过 PyPi 安装。重要的是，此目录是独立的，并且演示正常运行所需的任何文件都应存在。

额外 URL

文档生成器将生成一些按钮，向用户提供有用的信息和链接。有些是自动获取的，但有些需要明确包含在 pyproject.yaml 中。

• PyPi 版本和链接 - 这是自动生成的。
• GitHub 仓库 - 这是通过 pyproject.toml 的 project.urls.repository 填充的。
• Hugging Face Space - 这是通过 pyproject.toml 的 project.urls.space 填充的。

一个 pyproject.toml 的 urls 部分示例如下：

[project.urls]
repository = "https://github.com/user/repo-name"
space = "https://hugging-face.cn/spaces/user/space-name"