Building Documentation

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.

Conceptual architecture¶

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.

Prerequisites¶

To take advantage of Appium's documentation utilities, you'll need to install:

Python v3+
pip (this may be installed automatically with Python)

The @appium/docutils package:

npm install --save-dev @appium/docutils

Initializing an Extension for Building Docs¶

To prepare your extension for generating documentation, run the following command:

npx appium-docs init

This will:

Create a tsconfig.json if one does not already exist. This is necessary even if your extension is not written in TypeScript.
Create a mkdocs.yml with 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 them in docs, and add links to these files in mkdocs.yml.

Refer to the MkDocs documentation for information on how to organize and structure your documentation.

Helping LLMs Use Your Documentation¶

The /llms.txt convention is a Markdown file at the root of a documentation site, listing its most useful pages so that large language models can navigate the site without crawling it. Appium's own documentation provides one at appium.io/docs/en/latest/llms.txt, and you may want to do the same for your extension.

MkDocs copies any non-Markdown file in your docs directory to the built site as-is, so all you need to do is write an llms.txt and place it alongside your Markdown files. No plugin or build configuration is required.

The value of this file lies in the parts a crawler could not have worked out on its own, so it is worth writing by hand rather than generating it from your navigation:

A short description of what your extension automates, and which platforms it targets
The handful of things models reliably get wrong about your extension - removed capabilities, renamed commands, patterns from an older major version that no longer apply
Links to the pages that matter, with a description of each

Because links in llms.txt are read out of context, they must be absolute URLs. If you use Mike for versioning, point them at your version alias (for example latest) rather than at a pinned version, so that the file does not go stale. Note that a hand-written file can drift as pages are renamed; Appium validates its own with a script that runs in CI, which you are welcome to adapt.

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 examples:

# 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'