文档化自定义组件

在 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 和 Space 都具有以下功能

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

此外，Gradio 还包括

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

我需要做什么？

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

如果您已经在组件源代码中使用类型提示和 Docstrings，那么您无需做太多工作即可从该功能中受益，但仍有一些细节需要注意。

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

Docstrings 也被广泛用于提取 API 特定部分的更有意义、更易读的描述。

虽然 docstrings 没有语法要求，但为了文档目的，我们需要特定的结构。

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

• __init__ 参数的 Docstrings。
• preprocess 返回值的 Docstrings。
• postprocess 输入参数的 Docstrings。

其他所有内容都是可选的。

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

类

"""
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,
  ]

自定义事件

如果内置事件不适合您的用例，您可以定义自定义事件。这是一个简单的过程，但您必须以这种方式创建事件才能使 Docstrings 正常工作。

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，以及一个用于测试的更复杂的应用可能会更合理。您还可以创建其他 Spaces，展示更复杂的示例，并通过主类 Docstring 或 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"