构建文档

一旦您构建了驱动程序或构建了插件用于 Appium，您可能希望为您的用户记录该扩展是如何工作的。最基本的方法是编写一个简短的 README.md 并将其保存在项目的根目录中。但是，这可能需要很多努力。

Appium 项目构建了工具来帮助解决这个问题，我们已经将这些工具打包起来，以便构建驱动程序和插件的生态系统开发人员也可以使用它们。开始使用这些工具的最佳方法可能是查看现有的 Appium 驱动程序仓库，看看它是如何完成的，例如 XCUITest 驱动程序仓库。但是本指南将概述基本方法。

概念架构¶

Appium 选择了 MkDocs 作为基于 Markdown 的文档站点生成器。它使用 Python 工具链（而不是 Node.js），但事实证明它是我们目的的最佳选择。您可以调整它，但默认情况下，Appium 的实用程序也假设您将使用 mkdocs-material 主题/扩展用于 MkDocs。

为了使您的文档的不同版本可用（通常是针对扩展的每个次要版本），我们还捆绑了 Mike。

从这里开始，构建一个基本的文档站点就像将您的 Markdown 文件收集在一起并定义您希望它们如何组织一样简单。

先决条件¶

要利用 Appium 的文档实用程序，您需要安装

Python v3+
pip（这可能与 Python 一起自动安装）

@appium/docutils 包

npm install --save-dev @appium/docutils

初始化用于构建文档的扩展¶

要为您的扩展准备生成文档，请运行以下命令

npx appium-docs init

这将

创建一个 tsconfig.json（如果不存在）。即使您的扩展不是用 TypeScript 编写的，这也是必要的。
创建一个 mkdocs.yml，其中包含 MkDocs 的必要配置。

记录您的扩展¶

此时，您可以开始记录您的扩展。默认情况下，MkDocs 将在 docs 目录中查找 Markdown 文件。因此，您可以创建 Markdown 文档文件，将它们放在 docs 中，并在 mkdocs.yml 中添加指向这些文件的链接。

有关如何组织和构建文档的信息，请参阅 MkDocs 文档。

构建文档¶

此时，您可以使用 appium-docs CLI 工具。在没有参数的情况下运行此工具以获取完整的帮助输出，并查看所有可用的子命令和参数。以下是一些使用示例

# Generate reference and build the mkdocs site into the site dir
npx appium-docs build

# Same as build, but host the docs on a local dev server
# and watch for changes and rebuild when files change
npx appium-docs build --serve

# Build the docs and deploy them with mike versioning to the docs-site branch
# using the included commit message.
# This is particularly useful for pushing content to a GitHub pages branch!
npx appium-docs build \
  --deploy \
  -b docs-site \
  -m 'docs: auto-build docs for appium-xcuitest-driver@%s'