mirror of
https://github.com/appium/appium.git
synced 2026-10-18 05:36:35 +08:00
David Burns
a85a35e87d
* 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.
58 lines
1.6 KiB
YAML
58 lines
1.6 KiB
YAML
name: Build Docs
|
|
|
|
on:
|
|
pull_request:
|
|
branches:
|
|
- master
|
|
paths:
|
|
- '**/tsconfig*.json'
|
|
- '**/package*.json'
|
|
- '**/*mkdocs*.ya?ml'
|
|
- 'packages/docutils/requirements.txt'
|
|
- 'packages/*/README.md'
|
|
- 'packages/*/docs/**'
|
|
- 'packages/*/**/*.ts'
|
|
- 'packages/*/**/*.js'
|
|
- '.github/workflows/docs.yml' # this file
|
|
- '!**/test/**'
|
|
- '!**/sample-code/**'
|
|
push:
|
|
branches:
|
|
- master
|
|
paths:
|
|
- '**/tsconfig*.json'
|
|
- '**/package*.json'
|
|
- '**/*mkdocs*.ya?ml'
|
|
- 'packages/docutils/requirements.txt'
|
|
- 'packages/*/README.md'
|
|
- 'packages/*/docs/**'
|
|
- 'packages/*/**/*.ts'
|
|
- 'packages/*/**/*.js'
|
|
- '.github/workflows/docs.yml' # this file
|
|
- '!**/test/**'
|
|
- '!**/sample-code/**'
|
|
|
|
jobs:
|
|
docs:
|
|
name: Docs
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v7.0.1
|
|
- name: Install dependencies (Node.js)
|
|
uses: bahmutov/npm-install@v1.12.1
|
|
with:
|
|
useRollingCache: true
|
|
install-command: npm ci
|
|
- name: Install dependencies (Python)
|
|
run: PIP_BREAK_SYSTEM_PACKAGES=1 pip install -r packages/docutils/requirements.txt
|
|
- name: Configure Git User
|
|
run: |
|
|
git config --local user.email "github-actions[bot]@users.noreply.github.com"
|
|
git config --local user.name "github-actions[bot]"
|
|
- name: Check llms.txt
|
|
run: npm run docs:check-llmstxt
|
|
- name: Build Docs
|
|
run: npm run docs:preview
|
|
- name: Verify llms.txt was published to the site
|
|
run: test -s packages/appium/docs/site/en/llms.txt
|