docs: Create proof of concept mkdocs for docs/ dir (#864)

* Use mkdocstrings for library API reference
   * Update a selection of docstrings to improve formatting in the
     generated docs.
* Clean up some of the docstrings, type hints, etc.
* Use mkdocs-click for CLI reference
   * Did a pass through all the command docstrings and the result in the
     CLI reference to clean things up. Added minimal markdown
   * By default, mkdocs-click generates a big page with all the
     sub-commands included. For commands like `deadline job get` and
     `deadline queue get`, the anchor links get named like `#get` and
     `#get_1`, so won't be stable. It's also a lot to scroll through. I
     worked out a way to put each subcommand on its own page.
* Clean up the click main() function exposure.
    * Rename the primary handler from main() to deadline() internally,
      so that click uses the name 'deadline' without having to
      override prog_name.
    * Remove the file _deadline_cli.py as it is not necessary to avoid
      circular imports.
* Update the MCP tests to run based on the Python version, not whether
  the mcp library successfully imported.
* While reviewing the commands, updated 'deadline job wait' to print
  more information while polling. Example:
    Current status: SUCCEEDED (52/52 tasks succeeded, 0 workers running). [65.2s elapsed]

Signed-off-by: Mark <[email protected]>

Author: mwiebe

.github/workflows/mkdocs.yml

@@ -0,0 +1,33 @@
+name: Build and Deploy MkDocs
+
+on:
+  push:
+    branches:
+      - mainline
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/mkdocs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Install Hatch
+        run: |
+          pip install --upgrade hatch
+
+      - name: Build and deploy documentation
+        run: hatch run docs:deploy --force

.github/workflows/mkdocs_quality.yml

@@ -0,0 +1,34 @@
+name: MkDocs Quality Check
+
+on:
+  pull_request:
+    branches: [ mainline, release, feature_assets_cli, 'patch_*' ]
+  workflow_call:
+    inputs:
+      branch:
+        required: false
+        type: string
+      tag:
+        required: false
+        type: string
+permissions:
+  contents: write
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Install Hatch
+        run: |
+          pip install --upgrade hatch
+
+      - name: Build documentation
+        run: hatch run docs:build

.gitignore

@@ -13,8 +13,9 @@ __pycache__/
 .DS_Store
 
 # Build artifacts
-/build
-/dist
+/build/
+/dist/
+/site/
 installer/components
 
 # Misc extensions

DEVELOPMENT.md

@@ -5,7 +5,8 @@ This documentation provides guidance on developer workflows for working with the
 Table of Contents:
 * [Development Environment Setup](#development-environment-setup)
 * [The Development Loop](#the-development-loop)
-* [Code Organization](#code-organization)
+* [Documentation](#documentation)
+   * [Code Organization](#code-organization)
 * [Testing](#testing)
    * [Writing tests](#writing-tests)
    * [Unit tests](#unit-tests)
@@ -70,9 +71,17 @@ Note: Hatch uses [environments](https://hatch.pypa.io/1.12/environment/) to isol
 for this package from your system or virtual environment Python. If your build/test run is not making sense, then
 sometimes pruning (`hatch env prune`) all of these environments for the package can fix the issue.
 
-## Code Organization
+## Documentation
 
-Please see [code organization](docs/code_organization.md).
+Work-in-progress documentation for the Deadline Cloud client library is in progress in the [docs](docs/index.html) directory.
+Documentation is written in Markdown using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
+You can run the command `hatch run docs:serve` to start a server for viewing the documentation on localhost. When the command
+starts, it prints the URL for viewing the docs locally, and will automatically update them when the `mkdocs.yml` configuration
+or various markdown files are modified. The `hatch run docs:build` will build the documentation to static html content.
+
+### Code Organization
+
+Please see [code organization](docs/code_reference/code_organization.md).
 
 ## Testing
 
@@ -337,6 +346,6 @@ class MyCustomWidget(QWidget):
 
 # Profiling in Deadline Cloud
 
-Instead of runnning a deadline command as `deadline ...` run `pyinstrument -r html -m deadline ...`. 
+Instead of runnning a deadline command as `deadline ...` run `pyinstrument -r html -m deadline ...`.
 
-This will profile the current `deadline` command and open the results in an interactive window. 
+This will profile the current `deadline` command and open the results in an interactive window.

docs/cli_reference/deadline_attachment.md

@@ -0,0 +1,7 @@
+# Deadline CLI Reference
+
+::: mkdocs-click
+    :module: deadline.client.cli._groups.attachment_group
+    :command: cli_attachment
+    :prog_name: deadline attachment
+    :depth: 1

docs/cli_reference/deadline_auth.md

@@ -0,0 +1,7 @@
+# Deadline CLI Reference
+
+::: mkdocs-click
+    :module: deadline.client.cli._groups.auth_group
+    :command: cli_auth
+    :prog_name: deadline auth
+    :depth: 1

docs/cli_reference/deadline_bundle.md

@@ -0,0 +1,7 @@
+# Deadline CLI Reference
+
+::: mkdocs-click
+    :module: deadline.client.cli._groups.bundle_group
+    :command: cli_bundle
+    :prog_name: deadline bundle
+    :depth: 1

docs/cli_reference/deadline_config.md

@@ -0,0 +1,7 @@
+# Deadline CLI Reference
+
+::: mkdocs-click
+    :module: deadline.client.cli._groups.config_group
+    :command: cli_config
+    :prog_name: deadline config
+    :depth: 1

docs/cli_reference/deadline_farm.md

@@ -0,0 +1,7 @@
+# Deadline CLI Reference
+
+::: mkdocs-click
+    :module: deadline.client.cli._groups.farm_group
+    :command: cli_farm
+    :prog_name: deadline farm
+    :depth: 1

docs/cli_reference/deadline_fleet.md

@@ -0,0 +1,7 @@
+# Deadline CLI Reference
+
+::: mkdocs-click
+    :module: deadline.client.cli._groups.fleet_group
+    :command: cli_fleet
+    :prog_name: deadline fleet
+    :depth: 1