Merge pull request #409 from jumpstarter-dev/fix-warnings-and-links

Fix doc warnings and add additional doc targets

Author: raballew

.github/workflows/documentation.yaml

@@ -68,6 +68,27 @@ jobs:
         with:
           path: ./docs/build
 
+  check-warnings:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v1
+        with:
+          version: "latest"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install Python
+        run: uv python install
+
+      - name: Build the documentation for the current version (no warnings allowed)
+        run: make sync && make docs
+
   # Deployment job
   deploy:
     environment:

Makefile

@@ -2,6 +2,12 @@ PKG_TARGETS = $(subst packages/,,$(wildcard packages/*))
 
 default: build
 
+docs-singlehtml:
+	uv run --isolated --all-packages --group docs $(MAKE) -C docs singlehtml
+
+docs:
+	uv run --isolated --all-packages --group docs $(MAKE) -C docs html SPHINXOPTS="-W --keep-going -n"
+
 docs-all:
 	uv run --isolated --all-packages --group docs $(MAKE) -C docs multiversion
 

docs/source/conf.py

@@ -40,6 +40,11 @@
 
 mermaid_version = "10.9.1"
 
+suppress_warnings = [
+    "ref.class",  # suppress unresolved Python class references (external references
+                 # are warnings otherwise)
+]
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

docs/source/introduction/adapters.md

@@ -17,7 +17,4 @@ Unlike [Drivers](./drivers.md), which establish the foundational connections to
 
 ## Types of Adapters
 
-```{include} ../api-reference/adapters/index.md
-:start-after: "## Types of Adapters"
-:end-before: "```{toctree}"
-```
+* 📡 [Network](../api-reference/adapters/network.md): Adapters that transform network connections and streams into different protocols or connection types.

docs/source/introduction/drivers.md

@@ -22,12 +22,18 @@ patterns and examples, see the [Driver Classes and Architecture](../api-referenc
 
 Drivers are often used with [Adapters](./adapters.md), which transform driver connections into different forms or interfaces for specific use cases.
 
-## Types of Drivers
-
-```{include} ../api-reference/drivers/index.md
-:start-after: "## Types of Drivers"
-:end-before: "```{toctree}"
-```
+## Driver Types
+
+The API reference of the documentation provides a complete list of all drivers,
+you can find it here: [Driver API Reference](../api-reference/drivers/index.md).
+
+Some categories of drivers include:
+* ⚡ [System Control](../api-reference/drivers/index.md#system-control-drivers): Control power to devices, or general control.
+* 📡 [Communication](../api-reference/drivers/index.md#communication-drivers): Provide protocols for network communication, such as TCP/IP, Serial, CAN bus, etc.
+* 💾 [Storage And Data](../api-reference/drivers/index.md#storage-and-data-drivers): Control storage devices, such as SD cards or USB drives, and data.
+* 📹 [Media](../api-reference/drivers/index.md#media-drivers): Provide interfaces for media capture and playback, such as video or audio.
+* 🐞 [Debug and Programming](../api-reference/drivers/index.md#debug-and-programming-drivers): Provide interfaces for debugging and programming devices, such as JTAG or SWD, remote flashing, emulation, etc.
+* 🛠️ [Utility](../api-reference/drivers/index.md#utility-drivers): Provide utility functions, such as shell driver commands on a exporter.
 
 ### Composite Drivers
 

packages/jumpstarter-driver-corellium/README.md

@@ -25,10 +25,6 @@ export:
       # device_build: "Critical Application Monitor (Baremetal)"
 ```
 
-## API Reference
-
-For more examples, check the [examples folder](./examples).
-
 ### ExporterConfig Example
 
 You can run an exporter by running: `jmp exporter shell -c $file`: