From cb833c01df6ca6b3cef04628ebcb29dd22da71e8 Mon Sep 17 00:00:00 2001 From: Miguel Angel Ajo Pelayo Date: Mon, 14 Apr 2025 17:34:55 +0200 Subject: [PATCH 1/3] Fix doc warnings and add additional doc targets --- Makefile | 6 ++++++ docs/source/introduction/drivers.md | 18 ++++++++++++------ .../jumpstarter-driver-corellium/README.md | 4 ---- 3 files changed, 18 insertions(+), 10 deletions(-) diff --git a/Makefile b/Makefile index f7e64c391..81caf35f1 100644 --- a/Makefile +++ b/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 + docs-all: uv run --isolated --all-packages --group docs $(MAKE) -C docs multiversion diff --git a/docs/source/introduction/drivers.md b/docs/source/introduction/drivers.md index 847c839b8..7a7f50569 100644 --- a/docs/source/introduction/drivers.md +++ b/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 diff --git a/packages/jumpstarter-driver-corellium/README.md b/packages/jumpstarter-driver-corellium/README.md index e34a0fb89..ce746e5b1 100644 --- a/packages/jumpstarter-driver-corellium/README.md +++ b/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`: From 82c4c03d1ea8b69971cda3dffa7f0a9c6da4fd95 Mon Sep 17 00:00:00 2001 From: Miguel Angel Ajo Pelayo Date: Mon, 14 Apr 2025 17:39:33 +0200 Subject: [PATCH 2/3] Prevent future warnings by checking in CI --- .github/workflows/documentation.yaml | 21 +++++++++++++++++++++ Makefile | 2 +- docs/source/conf.py | 5 +++++ 3 files changed, 27 insertions(+), 1 deletion(-) diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml index 31cfe5301..07c24e6d3 100644 --- a/.github/workflows/documentation.yaml +++ b/.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: diff --git a/Makefile b/Makefile index 81caf35f1..88da82fad 100644 --- a/Makefile +++ b/Makefile @@ -6,7 +6,7 @@ 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 + 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 diff --git a/docs/source/conf.py b/docs/source/conf.py index 80e366d3e..1336dd32c 100644 --- a/docs/source/conf.py +++ b/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 From 1a70e0eda9f407e74247eddddb1d504c80cda608 Mon Sep 17 00:00:00 2001 From: Miguel Angel Ajo Pelayo Date: Mon, 14 Apr 2025 18:38:00 +0200 Subject: [PATCH 3/3] Fix adapters include for warnings --- docs/source/introduction/adapters.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/source/introduction/adapters.md b/docs/source/introduction/adapters.md index 96691479a..92934da0f 100644 --- a/docs/source/introduction/adapters.md +++ b/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}" -``` \ No newline at end of file +* 📡 [Network](../api-reference/adapters/network.md): Adapters that transform network connections and streams into different protocols or connection types. \ No newline at end of file