inverse symlinks to fix hatchling#399
Conversation
WalkthroughThis pull request restructures the driver documentation process. The Changes
Sequence Diagram(s)sequenceDiagram
participant S as create_driver.sh
participant D as Driver Directory
participant R as README.md
participant L as Documentation Symlink
S->>D: Define driver path and README.md location
S->>R: Create README.md with placeholders (DRIVER_CLASS, DRIVER_NAME)
S->>L: Create a symlink in docs directory pointing to README.md
Note over S: Removed previous conditional DOC_FILE check
Possibly related PRs
Suggested reviewers
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (79)
🧰 Additional context used🪛 LanguageTooldocs/source/api-reference/drivers/index.md[duplication] ~17-~17: Possible typo: you repeated a word. (ENGLISH_WORD_REPEAT_RULE) [duplication] ~29-~29: Possible typo: you repeated a word. (ENGLISH_WORD_REPEAT_RULE) [duplication] ~35-~35: Possible typo: you repeated a word. (ENGLISH_WORD_REPEAT_RULE) [duplication] ~40-~40: Possible typo: you repeated a word. (ENGLISH_WORD_REPEAT_RULE) packages/jumpstarter-driver-flashers/README.md[uncategorized] ~3-~3: You might be missing the article “the” here. (AI_EN_LECTOR_MISSING_DETERMINER_THE) [uncategorized] ~52-~52: Possible missing comma found. (AI_HYDRA_LEO_MISSING_COMMA) [style] ~53-~53: To make your writing flow more naturally, try moving ‘also’ before the verb. (ALSO_PLACEMENT) [style] ~284-~284: In American English, abbreviations like “etc.” require a period. (ETC_PERIOD) 🪛 markdownlint-cli2 (0.17.2)packages/jumpstarter-driver-flashers/README.md43-43: Heading style (MD003, heading-style) 126-126: Fenced code blocks should have a language specified (MD040, fenced-code-language) 170-170: Fenced code blocks should have a language specified (MD040, fenced-code-language) 195-195: Fenced code blocks should have a language specified (MD040, fenced-code-language) 266-266: Trailing punctuation in heading (MD026, no-trailing-punctuation) 271-271: Trailing punctuation in heading (MD026, no-trailing-punctuation) 272-272: Tables should be surrounded by blank lines (MD058, blanks-around-tables) 285-285: Table column count (MD056, table-column-count) 291-291: Table column count (MD056, table-column-count) ⏰ Context from checks skipped due to timeout of 90000ms (4)
🔇 Additional comments (84)
✨ Finishing Touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 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.
Caution
Inline review comments failed to post. This is likely due to GitHub's limits when posting large numbers of comments. If you are seeing this consistently it is likely a permissions issue. Please check "Moderation" -> "Code review limits" under your organization settings.
Actionable comments posted: 3
🧹 Nitpick comments (41)
docs/source/api-reference/drivers/can.md (1)
1-1: README Reference Added
A relative path to thejumpstarter-driver-canREADME file has been added. Consider formatting this as a markdown link (e.g.[README](../../../../packages/jumpstarter-driver-can/README.md)) to improve clickability in rendered views.docs/source/api-reference/drivers/qemu.md (1)
1-1: README Link Inclusion
The new relative path tojumpstarter-driver-qemu/README.mdis correctly added. Consider converting it into a markdown hyperlink for better usability (e.g.[README](../../../../packages/jumpstarter-driver-qemu/README.md)).docs/source/api-reference/drivers/yepkit.md (1)
1-1: README Link Added
The added relative reference to thejumpstarter-driver-yepkitREADME file is correct. As with other files, consider using markdown link syntax to enhance interactivity in rendered outputs.docs/source/api-reference/drivers/http.md (1)
1-1: README Reference Inserted
The relative path to the HTTP driver README (../../../../packages/jumpstarter-driver-http/README.md) has been added correctly. Again, consider converting it to a markdown hyperlink to benefit the rendered documentation.packages/jumpstarter-driver-raspberrypi/README.md (1)
1-26: New README for Raspberry Pi Driver
The newREADME.mdfor the Raspberry Pi driver is well structured with sections for installation, configuration, and API reference. Consider adding more detailed API documentation or a clear TODO note if the API section is still under development to set expectations for future updates.packages/jumpstarter-driver-qemu/README.md (2)
11-21: Configuration Section with Placeholder
The configuration example is concise and illustrative. The YAML snippet clearly shows how to configure the QEMU driver, although it still contains a placeholder comment ("# Add required parameters here").
Consider adding a note or linking to further documentation later, so users know to expect more detailed parameter guidance.
23-26: API Reference Section - Pending Content
The API Reference section is currently a placeholder ("Add API documentation here"). While this is acceptable in an initial commit, please ensure that comprehensive API details are provided in a subsequent update to maintain documentation completeness.packages/jumpstarter-driver-http/README.md (2)
11-21: Readable Configuration Example
The configuration section is clear and includes an example YAML snippet outlining how to set up the HTTP driver. Just like with the QEMU driver documentation, the placeholder for parameters ("# Add required parameters here") should eventually be replaced or expanded with detailed information.
23-26: Future Expansion for API Documentation
The API Reference section serves as a placeholder at this stage. It would be beneficial to update this section with comprehensive API details in future iterations to offer full guidance to users.packages/jumpstarter-driver-dutlink/README.md (1)
11-22: Informative Configuration Section
The YAML snippet provides an example configuration. The placeholder comment for required parameters is a good prompt; however, if possible, consider adding a concrete example or further guidance to aid users in configuring the driver.packages/jumpstarter-driver-power/README.md (1)
11-22: Detailed Configuration Example
The configuration section provides a YAML snippet that outlines how to set up the driver. Like the DUT Link driver, a placeholder is used for required parameters. If you have specific parameters or additional context, consider expanding on this section.packages/jumpstarter-driver-can/README.md (1)
11-22: Clear Configuration Example
The configuration section presents a YAML snippet that users can readily adapt. One minor suggestion: consider adding sample values or a link to more detailed parameter documentation if available, to further guide users.docs/source/api-reference/drivers/index.md (4)
12-16: System Control Drivers Section is Clear
The list entries for System Control Drivers are concise and use relative links for ease of navigation. A quick review of the text is recommended to ensure that any minor duplications in descriptive phrases (as hinted by static analysis) are intentional for clarity.
20-27: Communication Drivers Section is Consistent
The bullet list under Communication Drivers is well formatted with relative links. Please double-check the text for any repetitive wording as indicated by static analysis; this may be a stylistic choice but clearing it up could enhance readability.
32-33: Storage and Data Drivers are Documented Effectively
The storage drivers listed here are clear and correctly reference the associated packages. If further descriptive details are available, consider a brief note to guide the reader regarding any unique features.
40-44: Debug and Programming Drivers Section is Well Organized
The list of debug and programming drivers is comprehensive and the relative links are accurate. A small review for potential stylistic redundancies (as flagged by static analysis) might be useful, but overall this section is solid.🧰 Tools
🪛 LanguageTool
[duplication] ~40-~40: Possible typo: you repeated a word.
Context: ...unctionality ### Debug and Programming Drivers Drivers for debugging and programming devices: ...(ENGLISH_WORD_REPEAT_RULE)
packages/jumpstarter-driver-ustreamer/README.md (2)
11-17: Configuration Section is Nicely Handled
The use of a literal include for the YAML configuration (referencing “ustreamer.yaml”) is a practical approach that keeps the example DRY and maintainable. Just ensure that theustreamer.yamlfile is in the expected relative location so that the literal inclusion works as intended.
19-26: Doctest Effectively Documents Expected Error
The doctest snippet provides a clear example of how the configuration instantiation behaves, including the anticipated error. It might be helpful to add a brief comment explaining why anio.UnsupportedOperation: filenoerror is expected—this can assist users in understanding the limitations or intended behavior of the driver.packages/jumpstarter-driver-tftp/README.md (1)
11-23: Comprehensive Configuration SectionThe YAML configuration snippet is well-organized and specifies important parameters (e.g.,
root_dir,host, andport). The accompanying table further clarifies the parameters' types, requirements, and defaults.Consider adding a brief note explaining when and why each parameter might be adjusted (especially for optional ones like
hostandport).packages/jumpstarter-driver-network/README.md (1)
11-22: Configuration Section: Placeholder and GuidanceThe YAML snippet under the configuration section is clear but uses a placeholder comment (“# Add required parameters here”).
Consider updating the documentation with at least one concrete parameter example or a reference to additional documentation that details acceptable parameters for clarity.
packages/jumpstarter-driver-uboot/README.md (2)
1-3: Clarify and Enhance the Introduction
The header and introductory lines clearly state the purpose of the U-Boot driver and its dependency on external power and serial drivers. For added clarity, consider adding a brief note (or a link) on where to find details about configuring the ancillary drivers if available.
26-31: Autoclass Directive Formatting Recommendation
The API reference block uses the autoclass directive with a trailing “()” (i.e.UbootConsoleClient()). Standard Sphinx autodoc usage typically omits these parentheses. Consider changing-.. autoclass:: jumpstarter_driver_uboot.client.UbootConsoleClient() +.. autoclass:: jumpstarter_driver_uboot.client.UbootConsoleClientto ensure compatibility with Sphinx documentation tooling.
packages/jumpstarter-driver-sdwire/README.md (1)
19-26: Doctest Block and Expected Exception
The doctest clearly illustrates the expected error (i.e. a FileNotFoundError) when the SD-Wire device is missing. Ensure that this behavior is documented in the driver’s usage notes so users understand that this exception is expected under certain conditions.packages/jumpstarter-driver-snmp/README.md (2)
11-30: Comprehensive Configuration Section
The YAML configuration example is detailed and the following table offers a clear summary of each parameter, its type, and default value. This thoroughness helps users set up their environment correctly. No issues, but consider a brief note if any parameters have interdependencies or special constraints.
47-53: Autoclass Directive: Consistency Check
The API reference block uses:.. autoclass:: jumpstarter_driver_snmp.client.SNMPServerClient() :members: :show-inheritance:As with other files, reconsider using the class name without parentheses to adhere to Sphinx autodoc conventions:
-.. autoclass:: jumpstarter_driver_snmp.client.SNMPServerClient() +.. autoclass:: jumpstarter_driver_snmp.client.SNMPServerClientpackages/jumpstarter-driver-opendal/README.md (2)
11-17: Configuration Section VerificationThe configuration section is clearly demarcated and the example using a literal include for
opendal.yamlis a useful touch. Please confirm that the referenced file exists at the expected location and follows the correct format.
46-74: Comprehensive Client API DocumentationThe section documenting the client API using
autoclassdirectives is comprehensive. It documents several client classes (e.g.,OpendalClient,OpendalFile, etc.) in a uniform manner. Double-check that excluding themodel_configmember is intentional for every class.packages/jumpstarter-driver-shell/README.md (3)
1-4: Introduction Clarity and ConsistencyThe introduction is clear and succinct. However, you might consider adding one extra sentence that highlights the unique role or benefits of the shell driver (e.g., its ability to handle complex command execution scenarios) to give users immediate context about its value. Also, ensure consistency in using backticks for naming (e.g., `jumpstarter-driver-shell`).
11-34: Configuration Section CompletenessThe example configuration in YAML is well-structured and helps clarify how to set up the driver. A couple of points to consider:
- You may want to add a brief note – either as inline comments in the YAML or in accompanying text – explaining the role of the
driverfield (e.g., how `jumpstarter_driver_shell.driver.Shell` is used).- Verify that the naming conventions are consistent between the installation package name (
jumpstarter-driver-shell) and the internal module reference (jumpstarter_driver_shell), to avoid any potential confusion.
36-63: API Reference DocumentationThe API reference section is comprehensive and correctly uses reStructuredText directives to document the dynamically generated client methods. To further enhance the documentation:
- Consider adding concise descriptions for each method, including explanations of parameters and return value semantics. For example, a short note on how the tuple (stdout, stderr, return_code) is structured would benefit users.
- A small usage example for one of the methods could also help clarify its application.
__templates__/create_driver.sh (2)
35-63: Robust README.md Creation via Here-Document
Using a here-document with single quotes prevents premature variable expansion, and the subsequent use ofsedfor variable substitution ensures that the intended placeholders (${DRIVER_CLASS}and${DRIVER_NAME}) are correctly injected after file creation. This approach effectively decouples the file content from runtime variable interpolation.Note: Consider potential portability issues with
sed -isince BSD (macOS) sed may require an empty string as a backup extension (e.g.,sed -i '' ...) to work as expected.
64-68: Post-Processing with sed for Variable Expansion
The sed command correctly performs the replacement of placeholders in the README content. However, ensure that the values of${DRIVER_CLASS}or${DRIVER_NAME}do not contain characters that might interfere with the regular expression substitutions (for instance, characters with special meaning in regex).packages/jumpstarter-driver-flashers/README.md (9)
1-6: Suggestion: Clarify introductory phrasing.
The introduction is generally clear. However, consider revising “via network” to “via a network” (or “via the network”) to improve natural language flow.🧰 Tools
🪛 LanguageTool
[uncategorized] ~3-~3: You might be missing the article “the” here.
Context: ...rs are used to flash images to DUTs via network, typically using TFTP and HTTP. It is d...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
52-54: Suggestion: Improve phrasing for clarity.
Consider revising “In the above example we provide the serial and power children by reference, so those remain also available on the root of the exporter.” to something like:“In the above example, we provide the serial and power children via reference, so they remain available at the root of the exporter.”
This small change enhances readability.🧰 Tools
🪛 LanguageTool
[uncategorized] ~52-~52: Possible missing comma found.
Context: ...via HTTP | Yes | In the above example we provide the serial and power childre...(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~53-~53: To make your writing flow more naturally, try moving ‘also’ before the verb.
Context: ...en by reference, so those remain also available on the root of the exporter. ...(ALSO_PLACEMENT)
60-68: Suggestion: Adjust table spacing.
For improved readability, consider adding blank lines above and below the “Config parameters” table to better separate it from surrounding text.
125-130: Suggestion: Specify language for fenced code blocks.
The example following the “flash” command would benefit from an explicit language identifier (for example, using “```bash”) to ensure consistent syntax highlighting.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
126-126: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
169-176: Suggestion: Specify language for the bootloader-shell example.
Adding a language marker (such as “```bash”) to the bootloader-shell example code block will improve readability and consistency across examples.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
170-170: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
194-200: Suggestion: Specify language for the busybox-shell example.
Like the other examples, the busybox-shell example would benefit from explicitly specifying the language (e.g., “```bash”) in the fenced code block for consistency in syntax highlighting.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
195-195: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
266-266: Suggestion: Remove trailing punctuation from heading.
Consider changing “## The format of the manifest is as follows:” to “## The format of the manifest is as follows” (i.e. remove the colon) to adhere to markdown style guidelines.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
266-266: Trailing punctuation in heading
Punctuation: ':'(MD026, no-trailing-punctuation)
271-271: Suggestion: Remove trailing punctuation from heading.
Change “## Table with the spec fields of the manifest:” to “## Table with the spec fields of the manifest” to comply with style guidelines.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
271-271: Trailing punctuation in heading
Punctuation: ':'(MD026, no-trailing-punctuation)
1-304: Reminder: Verify symlink documentation.
The PR title mentions “inverse symlinks to fix hatchling,” yet this README does not explicitly address any changes related to symlink behavior. Please ensure that any required updates or clarifications regarding inverse symlinks are documented elsewhere or update this file if needed.🧰 Tools
🪛 LanguageTool
[uncategorized] ~3-~3: You might be missing the article “the” here.
Context: ...rs are used to flash images to DUTs via network, typically using TFTP and HTTP. It is d...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~52-~52: Possible missing comma found.
Context: ...via HTTP | Yes | In the above example we provide the serial and power childre...(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~53-~53: To make your writing flow more naturally, try moving ‘also’ before the verb.
Context: ...en by reference, so those remain also available on the root of the exporter. ...(ALSO_PLACEMENT)
[style] ~284-~284: In American English, abbreviations like “etc.” require a period.
Context: ...flashing, useful to clear boot entries, etc | | |kernel.file| Pa...(ETC_PERIOD)
🪛 markdownlint-cli2 (0.17.2)
43-43: Heading style
Expected: atx; Actual: setext(MD003, heading-style)
126-126: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
170-170: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
195-195: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
266-266: Trailing punctuation in heading
Punctuation: ':'(MD026, no-trailing-punctuation)
271-271: Trailing punctuation in heading
Punctuation: ':'(MD026, no-trailing-punctuation)
272-272: Tables should be surrounded by blank lines
null(MD058, blanks-around-tables)
285-285: Table column count
Expected: 3; Actual: 2; Too few cells, row will be missing data(MD056, table-column-count)
291-291: Table column count
Expected: 3; Actual: 2; Too few cells, row will be missing data(MD056, table-column-count)
🛑 Comments failed to post (3)
packages/jumpstarter-driver-sdwire/README.md (1)
28-35:
⚠️ Potential issueCritical: Verify the API Reference Module Name
The autoclass directive in this section references.. autoclass:: jumpstarter_driver_opendal.client.StorageMuxClient()Given that this README is for the jumpstarter-driver-sdwire package, the module name (
jumpstarter_driver_opendal) appears inconsistent. Please confirm if this is intentional (for example, if the SDWire driver reuses a shared storage multiplexer available in the opendal module). If it is a mistake, update the module name accordingly (e.g., tojumpstarter_driver_sdwire.client.StorageMuxClient).
Additionally, consider removing the trailing “()” for Sphinx autodoc compliance:-.. autoclass:: jumpstarter_driver_opendal.client.StorageMuxClient() +.. autoclass:: jumpstarter_driver_opendal.client.StorageMuxClientpackages/jumpstarter-driver-flashers/README.md (2)
43-50: 🛠️ Refactor suggestion
Critical Issue: Table formatting for children drivers.
The section meant to list the four children drivers is currently formatted as a broken and inconsistent table. This makes it hard to read and could confuse downstream processing by markdown parsers.
Consider reformatting it as follows:+**Flasher drivers require four children drivers:** + +| Child Driver | Description | +| ------------ | ------------------------------------------------------------------------------------ | +| serial | To communicate with the DUT via serial interface, driving the bootloader and busybox shell. | +| power | To control powering on and off of the DUT. | +| tftp | To serve binaries via TFTP. | +| http | To serve binaries via HTTP. |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.**Flasher drivers require four children drivers:** | Child Driver | Description | | ------------ | ------------------------------------------------------------------------------------ | | serial | To communicate with the DUT via serial interface, driving the bootloader and busybox shell. | | power | To control powering on and off of the DUT. | | tftp | To serve binaries via TFTP. | | http | To serve binaries via HTTP. |🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
43-43: Heading style
Expected: atx; Actual: setext(MD003, heading-style)
272-293: 🛠️ Refactor suggestion
⚠️ Potential issueCritical Issue: Inconsistent table column counts in the manifest spec table.
Some rows in this table (for example, the ones forkernel.fileanddtb.variants) appear to have only two cells instead of three. Each row should include a cell for the “Default” value—even if it is empty. For example:- | `kernel.file` | Path to kernel image within bundle + | `kernel.file` | Path to kernel image within bundle |Apply similar corrections to any affected rows to ensure the table renders correctly.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.| Field | Description | Default | | -------------------- | -------------------------------------------------------------------------- | ------- | | `manufacturer` | Name of the device manufacturer | | | `link` | URL to device documentation or manufacturer website | | | `bootcmd` | Command used to boot the device (e.g. booti, bootz) | | | `default_target` | Default target device to flash to if none specified | | | `targets` | Map of target names to device paths | | | `login.type` | Type of login shell | busybox | | `login.login_prompt` | Expected login prompt string | login: | | `login.username` | Username to log in with, leave empty if not needed | | | `login.password` | Password for login, leave empty if not needed | | | `login.prompt` | Shell prompt after successful login | # | | `preflash_commands` | List of commands to run before flashing, useful to clear boot entries, etc | | | `kernel.file` | Path to kernel image within bundle | | | `kernel.address` | Memory address to load kernel to | | | `initram.file` | Path to initramfs within bundle (if any) | | | `initram.address` | Memory address to load initramfs to (if any) | | | `dtb.default` | Default DTB variant to use | | | `dtb.address` | Memory address to load DTB to | | | `dtb.variants` | Map of DTB variant names to files | |🧰 Tools
🪛 LanguageTool
[style] ~284-~284: In American English, abbreviations like “etc.” require a period.
Context: ...flashing, useful to clear boot entries, etc | | |kernel.file| Pa...(ETC_PERIOD)
🪛 markdownlint-cli2 (0.17.2)
272-272: Tables should be surrounded by blank lines
null(MD058, blanks-around-tables)
285-285: Table column count
Expected: 3; Actual: 2; Too few cells, row will be missing data(MD056, table-column-count)
291-291: Table column count
Expected: 3; Actual: 2; Too few cells, row will be missing data(MD056, table-column-count)
3 participants
Summary by CodeRabbit
Documentation
Refactor
Style