docs: add plugin-related information (#2000)

* docs: adjust plugin-related information

* docs: integrate plugin readme into main docs

* docs: minor adjustments

* chore: prettier

Author: eglitise

README.md

@@ -37,13 +37,14 @@ When inspecting a mobile app, the Inspector looks like this:
 
 ## Installation
 
-Appium Inspector is released in two formats:
+Appium Inspector is released in 3 formats:
 
 1. Standalone desktop application for macOS, Windows, and Linux - download it from the
    [**Releases**](https://github.com/appium/appium-inspector/releases) section
 2. Web application - **<https://inspector.appiumpro.com>** (note that
    [CORS must be enabled](https://appium.github.io/appium-inspector/latest/troubleshooting/#cannot-start-a-session-using-browser-inspector)
    in order to connect to an Appium server)
+3. Appium server plugin - see the [**plugin README**](./plugins/README.md) for details
 
 Check the [System Requirements](https://appium.github.io/appium-inspector/latest/quickstart/requirements/)
 and [Installation](https://appium.github.io/appium-inspector/latest/quickstart/installation/)

docs/contributing.md

@@ -9,7 +9,7 @@ Want to contribute to this app? We'd love it!
 
 ## Code
 
-The code for this app is based on React and Electron.
+The application is primarily built using React, with the desktop app version being based on Electron.
 
 To start off, clone the project from GitHub and run:
 
@@ -28,7 +28,7 @@ npm ci
 Run in development mode:
 
 ```bash
-npm run dev:browser
+npm run dev:browser  # same as the plugin version
 npm run dev:electron
 ```
 
@@ -51,21 +51,23 @@ npm run test:e2e
 npm run test # lint, unit & integration
 ```
 
-Build the production version (desktop app into `/dist`, browser app into `/dist-browser`):
+Build the production version:
 
 ```bash
-npm run build:browser
-npm run build:electron
+npm run build:browser  # output directory: /dist-browser
+npm run build:plugin   # output directory: /plugins/dist-browser
+npm run build:electron # output directory: /dist
 ```
 
 Build the production version and run it:
 
 ```bash
 npm run preview:browser
+npm run preview:plugin
 npm run preview:electron
 ```
 
-Build the Electron app executable package (and other artifacts) for your platform into `/release`:
+Build the desktop app executable package (and other artifacts) for your platform into `/release`:
 
 !!! note
 
@@ -75,6 +77,13 @@ Build the Electron app executable package (and other artifacts) for your platfor
 npm run pack:electron
 ```
 
+Link the plugin version to your local Appium server:
+
+```bash
+cd plugins && npm install && cd ..           # install @appium/base-plugin
+appium plugin install --source=local plugins # link the plugin to Appium
+```
+
 ## Documentation
 
 The documentation for this app is built using Appium's own [`docutils`](https://github.com/appium/appium/tree/master/packages/docutils),

docs/overview.md

@@ -14,11 +14,13 @@ with a graphical user interface and additional features.
 
 ## Formats
 
-The Inspector is distributed in two formats:
+The Inspector is distributed in 3 formats:
 
 - Standalone desktop application for Windows, macOS, and Linux, available for download from
   [its GitHub repo](https://github.com/appium/appium-inspector/releases)
 - Web application, available at <https://inspector.appiumpro.com>
+- Appium server plugin, available for installation using
+  [Appium's Extension CLI](https://appium.io/docs/en/latest/cli/extensions/)
 
 Note that the web application may not be fully up-to-date with the desktop application.
 

docs/quickstart/index.md

@@ -15,4 +15,4 @@ This quickstart will cover the following:
 3. [Configure Appium session details](./starting-a-session.md)
 4. [Start an Inspector session](./starting-a-session.md#launching-the-session)
 
-Continue with the [installation requirements](./requirements.md)!
+Continue with the [system requirements](./requirements.md)!

docs/quickstart/installation.md

@@ -2,13 +2,46 @@
 title: Installation
 ---
 
-If you are using the Inspector's web app version, this step is, of course, not required. But if
-you wish to use the Inspector desktop app, it needs to be installed first.
+This step is only relevant if using the Inspector desktop app or Appium plugin formats.
+
+## Appium Plugin
+
+Like all Appium plugins, the Inspector plugin can be installed and activated using
+[the Appium command line](https://appium.io/docs/en/latest/cli/).
+
+1. Install the plugin:
+
+```bash
+appium plugin install --source=npm appium-inspector-plugin
+```
+
+!!! note
+
+    Appium 3 will also support the `appium plugin install inspector` command
+
+2. Launch the Appium server with the plugin activated:
+
+```bash
+appium --use-plugins=inspector --allow-cors
+```
+
+3. Open the Inspector URL in your web browser:
+
+```
+http://localhost:4723/inspector
+```
+
+!!! info
+
+    Make sure the above **host URL** and **port** match those of the Appium server. Note that the
+    server's base path value is ignored - the plugin always uses the `/inspector` path.
+
+## Desktop App
 
 The app can be downloaded from [the Inspector's GitHub repository](https://github.com/appium/appium-inspector/releases).
 Different file formats are provided for each supported platform.
 
-## Windows
+### Windows
 
 For Windows it is recommended to download the `.exe` installer file, as it supports [checking for updates](../menu-bar.md#update-checker).
 
@@ -30,7 +63,7 @@ Alternatively, you can also bypass this after having opened the installer:
 After following the installer steps, the Inspector app should be installed, and you should be able
 to open it without any warnings.
 
-## macOS
+### macOS
 
 For macOS it is recommended to download the `.dmg` file, as it supports [checking for updates](../menu-bar.md#update-checker).
 Opening the file will open a simple window, showing icons for the Inspector and the _Applications_ folder.
@@ -45,7 +78,7 @@ There are two ways to work around these warnings: using the macOS user interface
 command line. The user interface flows will differ depending on your macOS version, while the
 command line approach works for all macOS versions.
 
-### Command Line
+#### Command Line
 
 Simply open your Terminal app and run the following command:
 
@@ -55,7 +88,7 @@ xattr -cr "/Applications/Appium Inspector.app"
 
 You should now be able to open the app with no warnings.
 
-### UI - macOS Sequoia or later
+#### UI - macOS Sequoia or later
 
 With macOS Sequoia, Apple has tightened their security for installing non-notarized apps, so the
 required steps to allow opening the app have become more complex.
@@ -75,7 +108,7 @@ required steps to allow opening the app have become more complex.
 5. A prompt should appear, requiring you to confirm the action using administrator user credentials.
 6. After confirming the action, the app should open.
 
-### UI - macOS Sonoma or earlier
+#### UI - macOS Sonoma or earlier
 
 1. Upon opening the app, the following warning will be shown. Click _OK_.
    ![Appium Inspector Open Warning on macOS](./assets/images/open-warning-macos.png)
@@ -84,7 +117,7 @@ required steps to allow opening the app have become more complex.
 4. A prompt should appear - click _Open_ again.
 5. After accepting the prompt, the app should open.
 
-## Linux
+### Linux
 
 For Linux it is recommended to download the `.AppImage` file, as it supports [checking for updates](../menu-bar.md#update-checker).
 

docs/quickstart/requirements.md

@@ -5,31 +5,26 @@ hide:
 title: System Requirements
 ---
 
-Since the Inspector has two versions, [a desktop app and a web app](../overview.md#formats), the
-requirements for these will differ.
+Since the Inspector is released in [3 versions](../overview.md#formats), the requirements for these
+will differ:
 
-- Web app
-    - Works in Chrome/Edge/Firefox, released in 2022 or later
-      ([Safari is not supported](../troubleshooting.md#browser-version-does-not-work-in-safari))
-    - Viewport size of at least **870 x 610** pixels is recommended
 - Desktop app
     - Works on Windows 10+, macOS 11+, Ubuntu 18.04+, Debian 10+, openSUSE 15.5+, or Fedora Linux 39+
         - [These requirements are taken from Chrome](https://support.google.com/chrome/a/answer/7100626),
           as the Inspector is built using Electron (which uses Chromium)
     - Up to around **600MB** of free space is required
     - The minimum application window size is **890 x 710** pixels
+- Web app/Appium server plugin
+    - Works in Chrome/Edge/Firefox, released in 2022 or later
+      ([Safari is not supported](../troubleshooting.md#browser-version-does-not-work-in-safari))
+    - The plugin version requires around **9MB** of free space
+    - Viewport size of at least **870 x 610** pixels is recommended
 
-Both Inspector versions also require an **Appium server** to connect to, which is _not_ bundled with
-the Inspector. This server can be run either locally or remotely. If you need to install it, please
-check the [Appium Install documentation](https://appium.io/docs/en/latest/quickstart/install/)
-for details.
-
-!!! note
-
-    If using a standalone Appium server, make sure the server also has the necessary
-    [driver(s)](https://appium.io/docs/en/latest/ecosystem/drivers/) for your target platform(s)!
+All Inspector versions also require an **Appium server** to connect to, which can be hosted either
+locally or remotely. For instructions on how to install and set up the server, please refer to the
+[Appium documentation](https://appium.io/docs/en/latest/quickstart/install/). Make sure to also
+install the necessary [driver(s)](https://appium.io/docs/en/latest/ecosystem/drivers/) for your
+target platform(s).
 
-While the Inspector is designed to work with Appium 2, it is also compatible with
-later versions of Appium 1. Please be aware of
-[the differences between both Appium versions](https://appium.io/docs/en/latest/guides/migrating-1-to-2/) -
-in particular, the default server base path.
+Continue with the [Installation](./installation.md) steps, or jump directly to
+[Starting a Session](./starting-a-session.md)!

docs/quickstart/starting-a-session.md

@@ -31,12 +31,6 @@ information about the Appium server is specified, so that the Inspector knows ho
     - For a local or remote Appium server with non-default properties, please change the field
       values accordingly.
 
-!!! note
-
-    The above assumes that you are using Appium 2. If using Appium 1, the _Remote Path_ value
-    must be changed to `/wd/hub`. This may also apply to an Appium 2 server, if it was launched
-    with the `--base-path="/wd/hub"` argument.
-
 With the server details specified, you can move on to the session details!
 
 ## Adding Session Details

docs/session-builder/server-details.md

@@ -17,14 +17,13 @@ The default server details have 4 fields:
 
 ![Default Server Details](./assets/images/server-details/default-server-details.png)
 
-- **Remote Host**: the host URL of the server
-- **Remote Port**: the port on which the server is running
-- **Remote Path**: the path used to access the server. Appium 2 servers use `/` by default, whereas
-  Appium 1 servers use `/wd/hub`
-- **SSL**: by default, the server is accessed over HTTP - tick this checkbox to use HTTPS
+- **Remote Host**: the host URL of the server (default: `127.0.0.1`)
+- **Remote Port**: the port on which the server is running (default: `4723`)
+- **Remote Path**: the base path used to access the server (default: `/`)
+- **SSL**: whether HTTPS should be used when connecting to the server (default: `false`)
 
 If using the placeholder details, the Inspector will try to connect to `http://127.0.0.1:4723/`.
-If you have a locally-running Appium 2 server that was launched with default parameters, it should
+If you have a locally-running Appium server that was launched with default parameters, it should
 also be using this address, in which case you can leave the fields unchanged.
 
 ## Cloud Providers

package.json

@@ -37,6 +37,7 @@
     "build:plugin": "vite build --base /inspector --outDir ../../plugins/dist-browser",
     "build:electron": "electron-vite build",
     "preview:browser": "npm run build:browser && vite preview",
+    "preview:plugin": "npm run build:plugin && vite preview --base /inspector --outDir ../../plugins/dist-browser",
     "preview:electron": "electron-vite preview",
     "pack:electron": "electron-builder build --publish never",
     "clean": "npm run clean:electron && npm run clean:browser && npm run clean:npm && npm run clean:plugin",

plugins/README.md

@@ -3,50 +3,22 @@
 [![npm version](http://img.shields.io/npm/v/appium-inspector-plugin.svg)](https://npmjs.org/package/appium-inspector-plugin)
 [![Downloads](http://img.shields.io/npm/dm/appium-inspector-plugin.svg)](https://npmjs.org/package/appium-inspector-plugin)
 
-A plugin that integrates the [Appium Inspector](https://github.com/appium/appium-inspector) directly into your Appium server installation, providing a web-based interface for inspecting and interacting with your application under test.
+A plugin that integrates the [Appium Inspector](https://github.com/appium/appium-inspector) directly
+into your Appium server installation, providing a web-based interface for inspecting and interacting
+with your application under test.
 
 ## Features
 
-- Web-based Appium Inspector interface accessible via `/inspector` endpoint with appium server
+- Web-based Appium Inspector interface, accessible via the Appium server's `/inspector` endpoint
 - Full feature parity with standalone Appium Inspector
 
 ## Installation
 
-```bash
-appium plugin install --source=npm appium-inspector-plugin
-```
-
-> [!Note]
-> Appium 3 will support this plugin as a first-class plugin with `appium plugin install inspector`
-
-## Usage
-
-1. Start Appium server with the inspector plugin enabled:
-
-```bash
-appium --use-plugins=inspector --allow-cors
-```
-
-2. Access the Inspector interface by navigating to:
-
-```
-http://localhost:4723/inspector
-```
+Refer to the [Plugin Installation documentation](https://appium.github.io/appium-inspector/latest/quickstart/installation/#appium-plugin).
 
 ## Development
 
-1. `git clone` this repositiry
-2. Run `npm install` in `/path/to/appium-inspector/plugins`
-3. `appium plugin install --source=local /path/to/appium-inspector/plugins`
-4. Update the plugin content with `npm run build:plugin` in `/path/to/appium-inspector`
-5. Start Appium with `appium --use-plugins=inspector --allow-cors`
-
-## Release
-
-(TODO: add this release steps in .github/workflows/package.yml later as another PR)
-
-1. Run `npm run plugin:sync:version` to sync the version with the root project.json
-2. Run `npm publish` in `/path/to/appium-inspector/plugins` to publish the module
+Refer to the [Contributing documentation](https://appium.github.io/appium-inspector/latest/contributing/).
 
 ## License