自定义组件文档

在 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 文档，包括
  • 组件初始化的参数表，显示类型、默认值和描述。
  • 组件如何影响用户的 predict 函数的描述。
  • 事件表及其描述。
  • 初始化期间或在预处理器或后处理器中可能使用的任何其他接口或类。

此外，Gradio 还包括

• 一个实时演示。
• 更丰富、交互式的参数表版本。
• 更美观的样式！

我需要做什么？

文档生成器使用现有标准来提取必要的信息，即类型提示和文档字符串。没有 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
  ...

文档字符串

文档字符串也被广泛使用，以提取对 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，并为您的测试目的准备一个更复杂的应用程序可能更有意义。您还可以创建其他 Spaces，展示更复杂的示例，并从主类文档字符串或 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"