建立文件

一旦您為 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 必要設定的 mkdocs.yml。

說明您的擴充功能¶

在這個時候，您可以開始說明您的擴充功能。預設情況下，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'