* docs(appium): add llms.txt to the documentation site
Adds an /llms.txt file (https://llmstxt.org/) so that LLMs can navigate the
Appium documentation without crawling it, following the same approach taken by
the Selenium project.
The file is hand-written rather than generated. Its value lies in the parts a
crawler could not work out on its own: a set of steering notes covering what
models reliably get wrong about Appium (Appium 1 era patterns, drivers needing
separate installation, the `appium:` capability prefix, `mobile:` execute
methods, the Appium 3 `--allow-insecure` scope prefix, and the move from
GET /sessions to GET /appium/sessions), followed by conceptually grouped links
with a description for each page.
MkDocs copies non-Markdown files in docs_dir to the site verbatim, so this
requires no plugin, no new dependency and no build configuration. It is served
at appium.io/docs/en/latest/llms.txt, and mike gives a per-version copy for
free.
Because the file is hand-written, nothing regenerates it when a page is renamed
or removed. check-llmstxt.js validates it against the documentation sources and
runs on every docs PR: broken links fail the build, while pages that exist but
are not listed produce a warning (or fail under --strict).
The root of appium.io is not produced by MkDocs, but crawlers look for
/llms.txt at the domain root. Since the links in the file are absolute, the
same file serves both locations, so the publish workflow copies it to the
gh-pages root on release. mike only writes under its docs/<lang> deploy prefix,
so this does not interfere with it.
English only, matching Selenium and WebdriverIO. The ja/zh docs are translated
via Crowdin, where hand-edited descriptions would drift out of sync.
* docs(appium): address llms.txt review feedback
- Describe the standard W3C capabilities as the specification's set rather than
only browserName/browserVersion/platformName, so that generated code does not
vendor-prefix acceptInsecureCerts, timeouts, pageLoadStrategy or webSocketUrl.
- Say that these pages describe Appium 3, and that Appium 2 is documented under
its own version of the site, instead of claiming both are covered here.
- Note watchOS for the XCUITest driver, and the AI-related tools (Appium MCP,
agent skills) alongside Appium Inspector.
- Correct the event timings entry: the endpoint works without the
appium:eventTimings capability, which is being removed in Appium 4.
- check-llmstxt.js: a page that exists but is not listed is now an error rather
than a warning, since a warning in CI logs is easy to miss. The --strict flag
is gone, as that is now the only behaviour.
- check-llmstxt.js: validate relative and site-relative links too. A link such
as /docs/en/3.7/guides/caps/ was previously treated as external and skipped,
so a pinned version could have slipped past the check.
* fix(docutils): restore support for Python <3.12
* fix(docutils): only add the pip flag when required
* chore: fix lint
* chore: tune version number validation
* chore: address review comments
* chore: use env var to handle any pip version
* chore: remove unused import
* docs: add the env variable to zh docs
* fix: pass env vars properly on Windows
* chore: improve readability
The PR preview won't work when run from forks because there's no safe way to let forks write to our own `gh-pages` branch.
We'll need to find another strategy to get this working again.
For now, the docs build just builds the docs, like it did before.
This causes the "Build" workflow to only trigger if the PR modifies files in paths that might affect the build.
Likewise, the "Build Docs" workflow is expanded to rebuild docs if API changes occur (e.g. in sources).
Also restricts perms a bit more on docs build.
David Burns