docs: add MkDocs documentation (#1312)

* docs: create skeleton for MkDocs

* docs: add index and troubleshooting pages

* docs: add info on XCUI+RN source tree issue

* docs: add overview

* docs: use inspector icon everywhere

* docs: add CI job

* docs: add quickstart intro and requirements

* docs: add quickstart installation guide

* docs: finish quickstart

* docs: misc adjustments

* docs: use higher resolution icon

* docs: add contributing page

* docs: fix homepage

* fix: adjust tsconfig to silence errors

* docs: start session builder, add server details

* further group images into folders

* docs: fix more image links

* docs: add capability builder page

* docs: add saved caps sets and attach to session

* docs: augment quickstart with more links

* docs: add site to gitignore

* docs: add links in quickstart intro

* docs: tune attach to session

* docs: add session inspector intro

* docs: WIP header buttons

* docs: tune session builder some more

* docs: finish header page

* docs: WIP screenshot panel

* docs: finish screenshot panel

* docs: WIP source tab

* docs: add more info on group element handles

* docs: finish source tab

* docs: add commands tab

* docs: WIP gestures tab

* docs: tune some documents

* docs: finish gestures tab

* docs: fix link to session inspector

* docs: add recorder tab

* docs: add session info tab

* docs: tune everything

* docs: fix image size in README

* docs: fix branch name for edit button

* docs: run Prettier

* docs: add note for nested objects in caps

.github/workflows/build-docs.yml

@@ -0,0 +1,32 @@
+# Builds the Appium Inspector MkDocs documentation
+# Executed on pull request if documentation-related files are changed
+
+name: Build Docs
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'tsconfig.json'
+      - 'package*.json'
+      - '.github/workflows/build-docs.yml' # this file
+
+jobs:
+  docs:
+    name: Build Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js LTS
+        uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+          cache: 'npm'
+      - name: Install dependencies (Node.js)
+        run: npm install
+      - name: Install dependencies (Python)
+        run: npm run install-docs-deps
+      - name: Build Docs
+        run: npm run build:docs

.github/workflows/publish-docs.yml

@@ -0,0 +1,27 @@
+# Builds and publishes the Appium Inspector MkDocs documentation
+
+name: Publish Docs
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use GH Actions credentials
+        run: |
+          git config user.name github-actions
+          git config user.email github-actions@github.com
+      - name: Use Node.js LTS
+        uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+          cache: 'npm'
+      - name: Install dependencies (Node.js)
+        run: npm install
+      - name: Install dependencies (Python)
+        run: npm run install-docs-deps
+      - name: Build and deploy docs
+        run: npm run publish:docs

.gitignore

@@ -3,6 +3,7 @@ node_modules
 dist
 dist-browser
 release
+site
 main.map
 
 *.log

README.md

@@ -2,11 +2,11 @@
 
 [![Crowdin](https://badges.crowdin.net/appium-desktop/localized.svg)](https://crowdin.com/project/appium-desktop)
 
-![Appium Inspector icon](./docs/icon.png)
+<img src="./docs/assets/images/icon.png" alt="Appium Inspector Icon" width="128"/>
 
 A GUI inspector for mobile apps and more, powered by a (separately installed) Appium server. When you're using it to inspect a mobile app, it looks like this:
 
-![Appium Inspector screenshot](./docs/inspector-window.png)
+![Appium Inspector screenshot](./docs/assets/images/inspector-window.png)
 
 Appium Inspector is basically just an Appium client (like WebdriverIO, Appium's Java client, Appium's Python client, etc...) with a user interface. There's an interface for specifying which Appium server to use, which capabilities to set, and then interacting with elements and other Appium commands once you've started a session.
 
@@ -35,11 +35,11 @@ If you're using the desktop app on macOS, when you run it you may be greeted wit
 
 1. _Control+Click_ the Appium Inspector icon in the Applications Finder folder and choose `Open`.
 
-   ![Appium Inspector Ctrl+Click](./docs/mac-ctrl-click.png)
+   ![Appium Inspector Ctrl+Click](./docs/quickstart/assets/images/mac-ctrl-click.png)
 
 2. You'll be presented with the dialog below. Just click `Open` and Appium Inspector should launch.
 
-   ![Appium Inspector Open Warning](./docs/open-warning.png)
+   ![Appium Inspector Open Warning](./docs/quickstart/assets/images/open-warning.png)
 
 #### Method 2 - Command Line
 

docs/.prettierrc.json

@@ -0,0 +1,3 @@
+{
+    "tabWidth": 4
+}

docs/assets/stylesheets/extra.css

@@ -0,0 +1,6 @@
+.md-source__fact--version {
+    display: none;
+}
+.md-source__fact:nth-child(1n + 2):before {
+    margin-left: 0 !important;
+}

docs/contributing.md

@@ -0,0 +1,92 @@
+---
+hide:
+    - navigation
+
+title: Contributing
+---
+
+Want to contribute to this app? We'd love it!
+
+## Code
+
+The code for this app is based on React and Electron.
+
+To start off, clone the project from GitHub and run:
+
+```bash
+npm ci
+```
+
+!!! note
+
+    There are some possible requirements prior to the install due to
+    [`node-gyp`](https://github.com/nodejs/node-gyp#installation):
+
+      - [Python](https://www.python.org/)
+      - some C/C++ compiler tools matching your operating system
+
+Watch changes during development:
+
+```bash
+npm run dev           # desktop app
+npm run watch:browser # browser app
+```
+
+Start the production version of the desktop app:
+
+```bash
+npm run start
+```
+
+Run tests:
+
+```bash
+npm run test:lint
+npm run test:format
+npm run test:unit
+npm run test:integration
+npm run e2e
+
+npm run test # lint, unit & integration
+```
+
+Build the full app (desktop app into `/dist`, browser app into `/dist-browser`):
+
+```bash
+npm run build # desktop and browser
+npm run build:browser
+```
+
+Build the app executable package (and other artifacts) for your platform into `/release`:
+
+!!! note
+
+    For macOS, this requires code signing environment variables to be set.
+
+```bash
+npx electron-builder build --publish never
+```
+
+## Documentation
+
+The documentation for this app is built using Appium's own [`docutils`](https://github.com/appium/appium/tree/master/packages/docutils),
+which is based on [MkDocs](https://www.mkdocs.org/).
+
+To start off, clone the project from GitHub and install it as described in the [Code](#code)
+section. Then you can build the documentation:
+
+```bash
+npm run install-docs-deps # install the dependencies (Python packages)
+npm run dev:docs          # serve the docs locally and watch for changes
+```
+
+## Localization
+
+The Inspector code tries to use only localized strings (`t('localizationKey')`), which are
+synchronized with [Crowdin](https://crowdin.com/project/appium-desktop). If you would like to
+contribute translations, please leave your suggestions on Crowdin.
+
+If you find yourself needing to add completely new strings, first you need to make code changes that
+add the strings in the [English translation file](https://github.com/appium/appium-inspector/blob/main/assets/locales/en/translation.json).
+After your changes are merged, the new strings will be automatically added to Crowdin, and become
+available for translation into other languages.

docs/index.md

@@ -0,0 +1,38 @@
+---
+hide:
+    - navigation
+    - toc
+
+title: Welcome
+---
+
+<style>
+  .md-typeset h1 {
+    display: none;
+  }
+</style>
+
+<div style="text-align: center">
+  <img src="assets/images/icon.png" style="max-width: 200px;"/>
+</div>
+
+Welcome to the Appium Inspector documentation! The Inspector is a GUI assistant tool for Appium,
+providing visual inspection of the application under test (screenshots and page sources), with
+features such as interacting with the app screenshot, searching for and interacting with elements,
+executing driver actions, recording user actions, and more!
+
+Appium Inspector is part of the Appium ecosystem. For information on Appium itself, please visit
+[the Appium documentation](https://appium.io).
+
+## Explore the Documentation
+
+<div class="grid cards" markdown>
+
+-   Check out the [**Overview**](./overview.md) to learn the basics of the Inspector
+-   Go through the [**Quickstart**](./quickstart/index.md) steps to get set up and start inspecting your app
+-   The [**Session Builder**](./session-builder/index.md) section acts as a reference for the default landing screen
+-   The [**Session Inspector**](./session-inspector/index.md) section acts as a reference for the inspector screen
+-   Refer to the [**Troubleshooting**](./troubleshooting.md) page for a list of potential issues
+-   For contributions to the Inspector, refer to the [**Contributing**](./contributing.md) page
+
+</div>

docs/overrides/partials/toc-item.html

@@ -0,0 +1,44 @@
+<!--
+  Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to
+  deal in the Software without restriction, including without limitation the
+  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+  sell copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in
+  all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+  IN THE SOFTWARE.
+-->
+
+<!-- modified from https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/src/templates/partials/toc-item.html
+     for the purpose of not showing all heading objects in the TOC -->
+
+<!-- Table of contents item -->
+<li class="md-nav__item">
+  <a href="{{ toc_item.url }}" class="md-nav__link">
+    <span class="md-ellipsis">
+      {{ toc_item.title }}
+    </span>
+  </a>
+
+  <!-- Table of contents list -->
+  {% if toc_item.children and toc_item.level < 3 %}
+    <nav class="md-nav" aria-label="{{ toc_item.title | striptags }}">
+      <ul class="md-nav__list">
+        {% for toc_item in toc_item.children %}
+          {% include "partials/toc-item.html" %}
+        {% endfor %}
+      </ul>
+    </nav>
+  {% endif %}
+</li>

docs/overview.md

@@ -0,0 +1,63 @@
+---
+hide:
+    - navigation
+
+title: Overview
+---
+
+The main purpose of the Inspector is to provide inspection capabilities for the application page
+source. It is primarily intended to be used in test automation development, but it can also be
+useful in app development - or if one simply wants to take a look at an application's page source!
+
+Under the hood, the Inspector is essentially just an Appium client (based on [WebdriverIO](https://webdriver.io/)),
+with a graphical user interface and additional features.
+
+## Formats
+
+The Inspector is distributed in two 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>
+
+Note that the web application may not be fully up-to-date with the desktop application.
+
+## GUI Overview
+
+There are two main parts to the Inspector user interface:
+
+<div class="grid cards" markdown>
+
+-   **[The Session Builder](./session-builder/index.md)**
+    ![Session Builder](./assets/images/session-builder.png)
+    The default screen, where all the server and session details must be specified.
+
+-   **[The Session Inspector](./session-inspector/index.md)**
+    ![Session Inspector](./assets/images/session-inspector.png)
+    The active session screen, showing the app screenshot, page source, and more.
+
+</div>
+
+## Features Overview
+
+In addition to page source and screenshot inspection, the Inspector provides many other useful
+features. Here is a non-exhaustive list of such features:
+
+-   Easily define Appium server connection details and capabilities
+-   Save server details and capability sets for future sessions
+-   Connect to 10+ different cloud platforms
+-   Attach to an existing Appium session
+-   Interact with the application through its screenshot (click/tap, swipe)
+-   Create and save custom gestures
+-   Select elements directly through the application screenshot
+-   Search for elements using supported locator strategies and your own selectors
+-   Interact with elements (click/tap, send keys, clear)
+-   View suggested element locator strategies and selectors to be used in your scripts
+-   Compare the speed of different element finding strategies
+-   Record your actions directly into Appium client code for 5+ different programming languages
+-   Simulate system actions for iOS (home, Siri) and Android (back, home, app switch)
+-   Switch to different application contexts
+-   Access a library of various Appium driver commands
+
+All features are described in detail in the [Session Builder](./session-builder/index.md) and
+[Session Inspector](./session-inspector/index.md) sections.

docs/quickstart/index.md

@@ -0,0 +1,18 @@
+---
+hide:
+    - toc
+
+title: Quickstart Intro
+---
+
+Let's get started with Appium Inspector! Make sure you have checked out the
+[Overview](../overview.md) to understand the Inspector basics.
+
+This quickstart will cover the following:
+
+1. [Appium Inspector install requirements](./requirements.md)
+2. [Installing the Inspector](./installation.md)
+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)!