ドキュメントの構築

Appium用のドライバーを構築またはプラグインを構築したら、その拡張機能がユーザーにとってどのように機能するかをドキュメント化したいと思うでしょう。これを行う最も基本的な方法は、簡単なREADME.mdを作成し、プロジェクトのリポジトリのルートに保持することです。ただし、これには多くの労力がかかる場合があります。

Appiumプロジェクトには、これを支援するツールが組み込まれており、ドライバーとプラグインを構築するエコシステムの開発者がも使用できるようにこれらのツールをパッケージ化しました。これらのツールを使い始める最良の方法は、既存のAppiumドライバーのリポジトリを見て、それがどのように行われているかを確認することでしょう。たとえば、XCUITestドライバーリポジトリなどです。ただし、このガイドでは基本的なアプローチの概要を説明します。

概念アーキテクチャ¶

Appiumは、MarkdownベースのドキュメントサイトジェネレーターとしてMkDocsを採用しました。これはPythonツールチェーン（Node.jsではなく）を使用しますが、私たちの目的にとって最良のオプションであることがわかりました。これを調整することはできますが、デフォルトでは、Appiumのユーティリティは、MkDocsのmkdocs-materialテーマ/拡張機能も使用することを想定しています。

ドキュメントの異なるバージョン（通常は拡張機能のマイナーリリースごとに1つ）を利用できるようにするために、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'