@appium/mcp-documentation 1.0.3 → 1.0.4

package/src/resources/submodules/appium/packages/appium/docs/zh/developing/build-docs.md

@@ -0,0 +1,86 @@
+---
+title: Building Documentation
+---
+
+Once you've [built a driver](./build-drivers.md) or [built a plugin](./build-plugins.md) 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](https://github.com/appium/appium-xcuitest-driver). But this guide
+will outline the basic approach.
+
+### Conceptual architecture
+
+Appium settled on [MkDocs](https://www.mkdocs.org/) 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](https://squidfunk.github.io/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](https://github.com/jimporter/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+](https://www.python.org/downloads/)
+- [pip](https://pip.pypa.io/en/stable/installation/) (this may be installed automatically with Python)
+- The `@appium/docutils` package:
+
+  ```bash
+  npm install --save-dev @appium/docutils
+  ```
+
+### Initializing an Extension for Building Docs
+
+To prepare your extension for generating documentation, run the following command:
+
+```bash
+npx appium-docs init
+```
+
+This will:
+
+1. Create a `tsconfig.json` if one does not already exist. This is necessary even if your extension
+   is not written in TypeScript.
+2. 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](https://www.mkdocs.org/user-guide/writing-your-docs/) 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
+examples:
+
+```bash
+# 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'
+```

package/src/resources/submodules/appium/packages/appium/docs/zh/developing/build-doctor-checks.md

@@ -0,0 +1,141 @@
+---
+title: Building Doctor Checks
+---
+
+The idea of Appium Doctor is to assist users with driver or plugin preconditions setup. Sometimes such
+preconditions might be quite complicated and require non-trivial technical knowledge. Doctor checks,
+which are vanilla Node.js class instances written by extension authors, simplify
+the setup process by automating diagnostics and possible fixes for the found issues. These checks
+might also be interactive to ensure better usage experience.
+
+This tutorial is supposed to be used by plugin or driver authors that would like to help their users
+to deal with complicated setup or configuration steps.
+
+## Adding Doctor Checks
+
+### Typing Requirements
+
+The term `Doctor Check` literally describes a single javascript class instance that implements the
+[IDoctorCheck interface](https://github.com/appium/appium/blob/master/packages/types/lib/doctor.ts).
+The interface defines the following methods and properties:
+
+- `diagnose(): Promise<DoctorCheckResult>`: Contains the code to diagnose a possible issue
+- `fix(): Promise<string|null>`: Either fixes the actual problem if `hasAutofix()` returns true or
+  returns a string description for possible manual fixes. If this method throws an exception named
+  `FixSkippedError` and `hasAutofix()` returns true then the result of the method invocation
+  is going to be ignored.
+- `hasAutofix(): boolean`: Whether calling `fix()` would resolve the found issue
+- `isOptional(): boolean`: Whether the found issue can be ignored and is not a showstopper
+- `log: AppiumLogger`: May be used for logging. This property may be assigned
+  by the instance itself or by the Appium server if it is left unassigned.
+
+The `DoctorCheckResult` object returned by the `diagnose()` method must contain the following properties:
+
+- `ok: boolean`: Whether the diagnosis found no issues
+- `optional: boolean`: Whether the diagnosed issue is safe to ignore
+- `message: string`: The text message describing the diagnostic result
+
+### Manifest Requirements
+
+A single extension may export multiple Doctor checks to Appium. In order for these checks to be properly
+picked up by the server CLI after the corresponding extension is installed they might be listed in the
+package .json manifest under the `appium.doctor.checks` section similar to the definition below:
+
+```json
+  // ...
+  "appium": {
+    "driverName": "fake",
+    "automationName": "Fake",
+    "platformNames": [
+      "Fake"
+    ],
+    "mainClass": "FakeDriver",
+    "schema": "./build/lib/fake-driver-schema.js",
+    "scripts": {
+      "fake-error": "./build/lib/scripts/fake-error.js",
+      "fake-success": "./build/lib/scripts/fake-success.js",
+      "fake-stdin": "./build/lib/scripts/fake-stdin.js"
+    },
+    "doctor": {
+      "checks": [
+        "./doctor/fake1.js",
+        "./doctor/fake2.js"
+        // ...
+      ]
+    }
+  },
+  // ...
+```
+
+Also, it makes sense to include the [@appium/types](https://www.npmjs.com/package/@appium/types) import
+to the package dev dependencies.
+
+### Implementation Example
+
+The below example is a "raw" Node.JS implementation that does not use any transpilation:
+
+```js
+const {fs, doctor} = require('@appium/support');
+
+/** @satisfies {import('@appium/types').IDoctorCheck} */
+class EnvVarAndPathCheck {
+  /**
+   * @param {string} varName
+   */
+  constructor(varName) {
+    this.varName = varName;
+  }
+
+  async diagnose() {
+    const varValue = process.env[this.varName];
+    if (typeof varValue === 'undefined') {
+      return doctor.nok(`${this.varName} environment variable is NOT set!`);
+    }
+
+    if (await fs.exists(varValue)) {
+      return doctor.ok(`${this.varName} is set to: ${varValue}`);
+    }
+
+    return doctor.nok(`${this.varName} is set to '${varValue}' but this is NOT a valid path!`);
+  }
+
+  async fix() {
+    return (
+      `Make sure the environment variable ${this.varName} is properly configured for the Appium server process`
+    );
+  }
+
+  hasAutofix() {
+    return false;
+  }
+
+  isOptional() {
+    return false;
+  }
+}
+
+const androidHomeCheck = new EnvVarAndPathCheck('ANDROID_HOME');
+
+module.exports = {androidHomeCheck};
+
+/**
+ * @typedef {import('@appium/types').DoctorCheckResult} CheckResult
+ */
+```
+
+This file could be saved as `doctor/android-home-check.js` and then added to the package.json manifest
+as
+
+```json
+  // ...
+  "appium": {
+    // ...
+    "doctor": {
+      "checks": [
+        "./doctor/android-home-check.js",
+      ]
+    }
+    // ...
+  },
+  // ...
+```