Review documentation ahead of the next release - #24
Merged
Conversation
Text files normalize to LF in the repository and check out with the platform convention, and graphics assets are marked binary so they are never normalized. The template is extended with the file types this repository uses, including python-version, toml and css. Python sources carry the python diff driver, so diff hunk headers name the enclosing function or method rather than the enclosing class.
Examples and READMEs now pass a device module where they previously passed a Device subclass, and DatasetReader is documented as taking a module rather than a Device. Both stopped being accurate when the device constructor started taking the module as an argument. get_info omits the device argument entirely for schema-free access, since it reads only core registers. Example imports follow the module convention, so each register shows the module it came from at the call site, while protocol primitives stay imported by name where there is no origin to disambiguate. The SERIAL_PORT warning becomes a single fragment included by the four pages that use it. Prose across all markdown drops em-dashes, second-person address and parenthetical asides, and flows one line per paragraph. The contributing section documents pyright, which is what CI runs, rather than ty check, which is not installed. mkdocs drops four extensions that produced no change in the rendered output.
The benchmark report is now ASCII, so the UTF-8 console shim that both entry points carried is removed, along with the sys import it needed in generate. The report is written correctly under the platform default console encoding rather than depending on stdout being reconfigured. Declaration comments become docstrings below the name they document, replacing Sphinx #: markers and comments placed above. Griffe reads the docstring form and neither of the others, so these now reach the API pages, editor tooltips and the generated JSON schema. The device.yml model also gains a description on every field, taken from the upstream protocol schema. Docstrings and comments across the five packages and the test suite drop em-dashes, noun possessives, parenthetical asides and second-person address. The state-machine separators in the framer become ASCII rules.
bruno-f-cruz
requested changes
Aug 14, 2026
The dataset quickstart now reads by register class alongside the address, taking the class from reader.device_module so the example uses one device module throughout.
bruno-f-cruz
approved these changes
Aug 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation review ahead of the next release, in three commits that can be reviewed independently. The first is infrastructure, the substance is in the second and third.
Add gitattributes file
Adopts the
harp-tech/templatesfile verbatim, with three additions for a Python repository:*.python-version text,*.css text, anddiff=pythonon*.pyso diff hunk headers name the enclosing function rather than the enclosing class.Output-neutral.
git diffstayed empty after adding it, so nothing renormalized.Update documentation for the device module API
Corrects three instructions that stopped working after #17, #20 and #21:
harp-serial/README.mdtaught passing a generated device class toopen_serial_device. A generated device is a module.harp-data/README.mdand theread_datasetpage describedDatasetReaderas taking aharp.device.client.Device. Its parameter isDeviceModuleLike.harp.devicerather thanharp.device.core.Examples now import modules and qualify at the point of use, so
core.WhoAmIsits besidebehavior.AnalogDataand the origin of each register is visible at the call site.harp.protocolprimitives stay imported by name, where there is only one candidate module.get_infoomits the device argument entirely, which is the documented schema-free form and the honest one for an example that reads only core registers.The
SERIAL_PORTwarning becomes a single fragment included by the four pages that use it.mkdocs.ymldrops four extensions whose removal left the rendered site byte-identical, and the contributing section documentspyright, which is what CI runs, in place ofty check, which is not installed and fails.Prose across all markdown drops em-dashes, second-person address, noun possessives and parenthetical asides, and flows one line per paragraph.
Document declarations and sweep source prose
The benchmark report is now ASCII, so the UTF-8 console shim both entry points carried is gone. Verified by running the benchmark on a Windows console without it.
Declaration comments become docstrings below the name they document, replacing Sphinx
#:markers and comments placed above. Griffe reads only the docstring form, so none of the eleven#:comments were reaching the documentation. They now reach the API pages, editor tooltips and the generated JSON schema.The
device.ymlmodel gains a description on every field, taken from the upstreamprotocol/schema.