Unify the documentation layout and conventions - #41
Merged
glopesdev merged 5 commits intoAug 24, 2026
Merged
Conversation
Copy link
Copy Markdown
Contributor
Sorry, something went wrong.
bruno-f-cruz
approved these changes
Aug 23, 2026
glopesdev
force-pushed
the
pre-release-cleanup
branch
from
9785044 to
62b5323
Compare
August 24, 2026 00:32
glopesdev
force-pushed
the
pre-release-cleanup
branch
from
62b5323 to
ab7dee2
Compare
August 24, 2026 00:36
Test method docstrings become comments at the top of the method. Fixture docstrings stay, since pytest --fixtures prints them as output. Eight test names drop the article that made them read as sentences.
Example pages become index.md, shortening /examples/get_info/get_info/ to /examples/get_info/. The migration guide labels its Before and After blocks with bold lines rather than the title= fence attribute, which GitHub drops. The README gives the uv equivalent as a sentence rather than a second block, and settles on metapackage.
Prose says core registers rather than common in 23 places, matching the code and the specification. Dump now means only the register-dump operation, as it does on the documentation site, and recorded data is described as log files. The aggregate package is a metapackage, the protocol is the binary protocol rather than a wire format, and partial installs are for reading recorded data rather than offline dumps. The README states what the project is and links out for what Harp is, its package list is rewritten and reordered to match the dependency order of the table below it, and that table drops the column that duplicated the list. The migration guide is unwrapped to one line per paragraph, matching every other markdown file.
Example pages move from a directory each to flat files under docs/examples with their scripts as siblings, renamed for their subject rather than for an operation. URL segments use hyphens and script filenames keep underscores. Removing the examples index page makes Examples a section label rather than a page, matching API. The runtime and generated module trade-off moves out of the schema example into a new article that names and defines the device module term. Titles and nav labels are sentence case and mirror each other, the root label becomes Introduction, and the nav runs Introduction, Examples, Guides, API. The migration guide file is shortened to harp-python-migration, and the README drops its link to the removed examples index.
Headings no longer open with an -ing form, taking an imperative or a noun phrase instead, and nav labels follow the titles they mirror. The verb reach gives way to the one that fits each sense, and a prose pass shortens over-long sentences and tightens wording and punctuation throughout. Two test functions follow the same rules, and the migration guide gains a paragraph on the identity check a generated package makes possible.
glopesdev
force-pushed
the
pre-release-cleanup
branch
from
ab7dee2 to
07d3d7b
Compare
August 24, 2026 00:44
glopesdev
added a commit
that referenced
this pull request
Aug 24, 2026
Example pages move from a directory each holding an index.md to flat files under docs/examples, with their scripts as flat siblings, which under use_directory_urls produces the same URLs as a directory. The examples index page is removed, so Examples becomes a section label rather than a page. Folders and files are renamed for their subject rather than for an operation, URL segments use hyphens, and Python filenames keep underscores. The trade-off between a generated package and a runtime module moves out of the schema example into its own article, which names and defines the device module term. The nav runs Introduction, Examples, Guides, API, with Introduction replacing Home. Page titles and nav labels are sentence case and mirror each other, and no heading opens with an -ing form. The verb reach is replaced by the one that fits each sense, over-long sentences are split, and stray parentheses and semicolons give way to plain sentences. Test names drop articles and test docstrings become comments.
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
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.
The documentation had drifted on four axes at once: how a page is laid out on disk, how its path is spelled, how its title relates to its navigation label, and which word names which idea. This converges each on a single rule. A page is a flat file whose name is its URL segment, a path is a noun naming its subject, a title is sentence case and mirrors its label, and a term carries one sense.
Structure
Example pages move from a directory each holding an index.md to flat files under docs/examples, with their scripts as flat siblings. Under use_directory_urls a flat device-info.md and a device-info/index.md produce the same /examples/device-info/, so the layout simplifies at no cost to the published paths. Removing the examples index page makes Examples a section label rather than a page, matching API.
Folders and files are renamed for their subject rather than for an operation, so get_info becomes device-info and create_device_module becomes registers-from-schema. URL segments use hyphens and Python filenames keep underscores, each separator used for what it means.
The trade-off between a generated package and a runtime module moves out of the schema example into docs/articles/device-modules.md, which now names and defines the device module term used throughout the rest of the documentation.
Navigation
The nav runs Introduction, Examples, Guides, API. Introduction replaces Home, matching the toolkit site. The articles/ path is kept for consistency with every other DocFX site in the organization, while the section label reads Guides.
Prose
Page titles and navigation labels are sentence case and mirror each other so they cannot drift. No heading opens with an -ing form, which both the Google and Microsoft style guides advise against, with Contributing the one entrenched exception.
reach was carrying four senses across the docs, the READMEs and the tests: accessing a register, a register passed as an argument, targeting a session folder, and arriving at a code branch. Each now takes the verb that fits it. Over-long sentences are split, anthropomorphisms and stranded verbs are rewritten, and stray parentheses and semicolons give way to plain sentences.
Tests
Test names drop articles, test docstrings become comments, and two functions follow the vocabulary above.