Once you've built a driver or built a plugin for Appium,
you will hopefully want to document how that extension works for your users. The most basic way of
doing this is to write up a quick
README.md and keep it in the root of your project's repository.
However, this can involve a lot of effort.
The Appium project has built tools to help with this, and we've packaged up these tools so our ecosystem developers building drivers and plugins can also use them. The best way to get going with these tools is probably to look at an existing Appium driver repo to see how it's done, for example the XCUITest driver repo. But this guide will outline the basic approach.
Appium settled on MkDocs as a Markdown-based documentation site generator. It uses a Python toolchain (and not Node.js), but it turned out to be the best option for our purposes. You can adjust this, but by default Appium's utilities also assume that you'll be using the mkdocs-material theme/extension for MkDocs.
In order to make different versions of your docs available (one for each minor release of your extension, typically), we also bundle Mike.
From here, building a basic docs site is as easy as collecting your Markdown files together and defining how you want them to be organized.
To take advantage of Appium's documentation utilities, you'll need to install:
Initializing an Extension for Building Docs¶
To prepare your extension for generating documentation, run the following command:
- Create a
tsconfig.jsonif one does not already exist. This is necessary even if your extension is not written in TypeScript.
- Create a
mkdocs.ymlwith the necessary configuration for MkDocs.
Documenting Your Extension¶
At this point, you can begin documenting your extension. By default, MkDocs will look for Markdown
files in the
docs directory. You can therefore create your Markdown documentation files, place
docs, and add links to these files in
Refer to the MkDocs documentation for information on how to organize and structure your documentation.
Building the Docs¶
At this point, you can use the
appium-docs CLI tool. Run this tool with no arguments to get the
full help output and see all the available subcommands and parameters. Here are a few usage
# 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 \
-b docs-site \
-m 'docs: auto-build docs for appium-xcuitest-driver@%s'