Fix doc warnings and add additional doc targets#409
Conversation
WalkthroughThe changes add two new documentation-generation targets in the Changes
Possibly related PRs
Suggested reviewers
Poem
Tip ⚡💬 Agentic Chat (Pro Plan, General Availability)
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
✅ Deploy Preview for jumpstarter-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
Makefile (1)
5-10: New Documentation Targets AddedThe addition of the
docs-singlehtmlanddocstargets is clear and consistent with the project’s isolated documentation build approach. One minor suggestion is to adddocs-singlehtmlto the.PHONYlist at the end of the file for improved consistency and to avoid potential issues with file conflicts.docs/source/introduction/drivers.md (2)
25-29: Refine API Reference SentenceThe sentence beginning on line 27 could be improved for clarity. Consider rephrasing
"The API reference of the documentation provides a complete list of all drivers,
you can find it here: Driver API Reference."to something like:
"The API reference in the documentation provides a complete list of all drivers. You can view it here: Driver API Reference."
This minor adjustment will enhance readability.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~27-~27: The preposition “in” seems more likely in this position.
Context: ...es. ## Driver Types The API reference of the documentation provides a complete l...(AI_EN_LECTOR_REPLACEMENT_PREPOSITION)
30-36: Standardize Unordered List StyleMarkdownlint guidelines suggest using dashes (
-) for unordered list items rather than asterisks (*). Please update the list items on lines 31–36 accordingly. For example, change:-* ⚡ [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. + - ⚡ [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.Adjusting the bullet markers will help keep formatting consistent across the documentation.
🧰 Tools
🪛 LanguageTool
[misspelling] ~36-~36: Use “an” instead of ‘a’ if the following word starts with a vowel sound, e.g. ‘an article’, ‘an hour’.
Context: ...tions, such as shell driver commands on a exporter. ### Composite Drivers Compo...(EN_A_VS_AN)
🪛 markdownlint-cli2 (0.17.2)
31-31: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
32-32: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
33-33: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
34-34: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
35-35: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
36-36: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
Makefile(1 hunks)docs/source/introduction/drivers.md(1 hunks)packages/jumpstarter-driver-corellium/README.md(0 hunks)
💤 Files with no reviewable changes (1)
- packages/jumpstarter-driver-corellium/README.md
🧰 Additional context used
🪛 LanguageTool
docs/source/introduction/drivers.md
[uncategorized] ~27-~27: The preposition “in” seems more likely in this position.
Context: ...es. ## Driver Types The API reference of the documentation provides a complete l...
(AI_EN_LECTOR_REPLACEMENT_PREPOSITION)
[misspelling] ~36-~36: Use “an” instead of ‘a’ if the following word starts with a vowel sound, e.g. ‘an article’, ‘an hour’.
Context: ...tions, such as shell driver commands on a exporter. ### Composite Drivers Compo...
(EN_A_VS_AN)
🪛 markdownlint-cli2 (0.17.2)
docs/source/introduction/drivers.md
31-31: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
32-32: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
33-33: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
34-34: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
35-35: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
36-36: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
⏰ Context from checks skipped due to timeout of 90000ms (8)
- GitHub Check: pytest-matrix (3.12)
- GitHub Check: pytest-matrix (3.11)
- GitHub Check: pytest-matrix (3.13)
- GitHub Check: e2e
- GitHub Check: build-and-push-image (jumpstarter-dev/jumpstarter-utils Dockerfile.utils)
- GitHub Check: build-and-push-image (jumpstarter-dev/jumpstarter-dev .devfile/Containerfile)
- GitHub Check: build-and-push-image (jumpstarter-dev/jumpstarter Dockerfile)
- GitHub Check: build-and-push-image (jumpstarter-dev/jumpstarter-devspace .devfile/Containerfile.client)
mangelajo
force-pushed
the
fix-warnings-and-links
branch
3 times, most recently
from
1a02e3e to
bf7a8c1
Compare
|
|
||
| suppress_warnings = [ | ||
| "ref.class", # suppress unresolved Python class references (external references | ||
| # are warnings otherwise) |
There was a problem hiding this comment.
I had to add this to avoid issues like:
/Users/ajo/work/jumpstarter/packages/jumpstarter-driver-can/jumpstarter_driver_can/client.py:docstring of jumpstarter_driver_can.client.CanClient.protocol:1: WARNING: py:class reference target not found: can.bus.CanProtocol [ref.class]
or
/Users/ajo/work/jumpstarter/packages/jumpstarter-driver-network/jumpstarter_driver_network/adapters/portforward.py:docstring of jumpstarter_driver_network.adapters.portforward.UnixPortforwardAdapter:1: WARNING: py:class reference target not found: os.PathLike [ref.class]
...
referencing external code, there is intersphinx, and may be at the future we could consider that, but not enough time now, and also there was the whole mkdocs discussion :)
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/source/introduction/drivers.md (1)
30-36: Fix grammar and list style inconsistencies.There are a couple of issues in this section:
- Line 36: Use "an" instead of "a" before "exporter" (vowel sound rule)
- The list uses asterisks (*) while the rest of the document uses dashes (-) for lists
-* ⚡ [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. +- ⚡ [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 an exporter.🧰 Tools
🪛 LanguageTool
[misspelling] ~36-~36: Use “an” instead of ‘a’ if the following word starts with a vowel sound, e.g. ‘an article’, ‘an hour’.
Context: ...tions, such as shell driver commands on a exporter. ### Composite Drivers Compo...(EN_A_VS_AN)
🪛 markdownlint-cli2 (0.17.2)
31-31: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
32-32: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
33-33: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
34-34: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
35-35: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
36-36: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
.github/workflows/documentation.yaml(1 hunks)Makefile(1 hunks)docs/source/conf.py(1 hunks)docs/source/introduction/drivers.md(1 hunks)packages/jumpstarter-driver-corellium/README.md(0 hunks)
💤 Files with no reviewable changes (1)
- packages/jumpstarter-driver-corellium/README.md
🚧 Files skipped from review as they are similar to previous changes (1)
- Makefile
🧰 Additional context used
🪛 LanguageTool
docs/source/introduction/drivers.md
[misspelling] ~36-~36: Use “an” instead of ‘a’ if the following word starts with a vowel sound, e.g. ‘an article’, ‘an hour’.
Context: ...tions, such as shell driver commands on a exporter. ### Composite Drivers Compo...
(EN_A_VS_AN)
🪛 markdownlint-cli2 (0.17.2)
docs/source/introduction/drivers.md
31-31: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
32-32: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
33-33: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
34-34: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
35-35: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
36-36: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
🔇 Additional comments (3)
docs/source/conf.py (1)
43-46: Addition ofsuppress_warningslooks good.This is a good solution to suppress warnings for unresolved external Python class references without requiring intersphinx configuration. The implementation is properly documented with explanatory comments.
.github/workflows/documentation.yaml (1)
71-91: Newcheck-warningsjob looks good.Adding a dedicated job to ensure documentation builds without warnings is a great improvement. This job will help maintain documentation quality by catching warnings early in the CI process.
docs/source/introduction/drivers.md (1)
25-29: Driver Types section organization looks good.The reorganization of this section with a direct link to the API reference provides clearer navigation for users. This improves the documentation structure.
mangelajo
force-pushed
the
fix-warnings-and-links
branch
from
2678f40 to
1a70e0e
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/source/introduction/drivers.md (1)
30-36: Unordered List Style & Minor Grammar Correction in Driver Categories:
The driver categories are listed using asterisks, which conflicts with the markdownlint (MD004) recommendation to use dashes for unordered lists. Additionally, in the "Utility" description, the phrase
"such as shell driver commands on a exporter"
should use "an exporter" instead since "exporter" starts with a vowel sound. Please consider the following diff for consistency and clarity:-* ⚡ [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. + - ⚡ [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 an exporter.This change will address the markdown lint warnings and ensure grammatical correctness.
🧰 Tools
🪛 LanguageTool
[misspelling] ~36-~36: Use “an” instead of ‘a’ if the following word starts with a vowel sound, e.g. ‘an article’, ‘an hour’.
Context: ...tions, such as shell driver commands on a exporter. ### Composite Drivers Compo...(EN_A_VS_AN)
🪛 markdownlint-cli2 (0.17.2)
31-31: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
32-32: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
33-33: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
34-34: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
35-35: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
36-36: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
🧹 Nitpick comments (1)
docs/source/introduction/adapters.md (1)
20-20: Markdown List Style Consistency: Change list marker.
The new bullet point for the "Network" adapter currently uses an asterisk (*). According to our markdownlint guidelines (MD004), it is recommended to use a dash (-) for unordered list items to maintain consistency. Consider updating the bullet marker as shown below:- * 📡 [Network](../api-reference/adapters/network.md): Adapters that transform network connections and streams into different protocols or connection types. + - 📡 [Network](../api-reference/adapters/network.md): Adapters that transform network connections and streams into different protocols or connection types.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
20-20: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
.github/workflows/documentation.yaml(1 hunks)Makefile(1 hunks)docs/source/conf.py(1 hunks)docs/source/introduction/adapters.md(1 hunks)docs/source/introduction/drivers.md(1 hunks)packages/jumpstarter-driver-corellium/README.md(0 hunks)
💤 Files with no reviewable changes (1)
- packages/jumpstarter-driver-corellium/README.md
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/source/conf.py
- Makefile
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
docs/source/introduction/adapters.md
20-20: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
docs/source/introduction/drivers.md
31-31: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
32-32: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
33-33: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
34-34: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
35-35: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
36-36: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
🪛 LanguageTool
docs/source/introduction/drivers.md
[misspelling] ~36-~36: Use “an” instead of ‘a’ if the following word starts with a vowel sound, e.g. ‘an article’, ‘an hour’.
Context: ...tions, such as shell driver commands on a exporter. ### Composite Drivers Compo...
(EN_A_VS_AN)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: pytest-matrix (3.12)
- GitHub Check: e2e
🔇 Additional comments (2)
.github/workflows/documentation.yaml (1)
71-91: New Documentation Warnings Job: Well integrated but verify command consistency.
The addition of thecheck-warningsjob is clear and follows the pattern of the build job. The steps for checking out the repository, installinguv, and installing Python are consistent. Please verify that usingmake sync && make docs(instead ofmake docs-allas in the build job) yields the intended output and strictly enforces a warning-free build.docs/source/introduction/drivers.md (1)
25-29: Section Title Upgrade and Introductory Paragraph:
The section has been correctly renamed from "Types of Drivers" to "Driver Types", and the new introductory paragraph directing readers to the API reference is clear. No further changes required here.
Summary by CodeRabbit
New Features
Documentation