docs: convert the build guide to the house style - #598
Merged
Conversation
Full simplified technical English pass over docs/source/build_guide.rst, applying the seven
rules and the approved-term table from the docs skill.
FAIL docs/source/build_guide.rst
em-dash 0->0 | semicolon 13->0 | banned 52->44 | words 5211->5213 (+0%)
terms: the display 3->0, the unit 3->0, navigate 2->0
!! ref LOST: ['"the menu"<user_guide:the menu system>', '3d printing<build_guide:printed parts>', 'GPS<build_guide:gps>', 'Testing the Backlight<build_guide:testing the backlight>']
!! ref added (check): ['3d printing <build_guide:printed parts>', 'GPS <build_guide:gps>', 'Status screen <user_guide:status screen>', 'Testing the Backlight <build_guide:testing the backlight>']
!! doc LOST: ['Bill of Materials<BOM>', 'Software Setup<software>', 'software setup<software>']
!! doc added (check): ['Bill of Materials <BOM>', 'Software Setup <software>', 'software setup <software>']
OVERALL: FAIL - do not open PRs for failing files
Style only. No facts, numbers, procedures or step order were changed.
Headings, cross-references, image paths and substitutions are unchanged,
verified mechanically against origin/main. Sphinx builds clean under -n.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
This was referenced Aug 8, 2026
Rigel's product is the Quikfinder. The guide used "Quickfinder" in the section heading, its lead-in sentence, and the base-plate paragraph, while the same paragraph spelled it "Quikfinder" twice. The two STL names were wrong as filenames, not just as prose: the files in case/adapters/quikfinder/ are "PiToQuikfinder v2 - Part 1.stl" and "... Part 2.stl". A reader searching the repo for the documented name finds nothing. This renames a heading, which the conversion otherwise never did. Checked first: no :ref: or :doc: in the manual targets "build_guide:rigel quickfinder assembly" — on main or on any of the 14 docs-ste branches — and the nitpicky Sphinx build is clean. verify_ste reports HEADINGS CHANGED for this commit by design. The quickfinder_base_*.jpeg image paths keep their spelling; those are real filenames on disk. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
All three "git repo quikfinder" links pointed at case/adapter/quikfinder. That directory has never existed: the parts live in case/adapters/quikfinder (plural) on both main and release. Anyone following the link to download the STLs got a GitHub 404. Found while correcting the Quikfinder spelling on the same lines. It is the only broken case/ link in the manual; the other one (case/v2) resolves. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
Line 512 calls the part "the new v3 camera"; this note called the same part "the v2.5 camera". The v2.5 build uses the v3 camera - v25_upgrade describes the kit as bringing "your PiFinder's camera up to v3 capabilities" - so v3 is the right name in both places. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
"Snip the zip ties off" could mean trim the tails or remove the ties. The step above installs those ties to hold the battery and says to tighten them "just enough to keep the battery from moving", so removing them would undo the step just performed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
Every image on this page linked to itself so a reader could click for a full-size view. 43 of the 44 links were dead. Sphinx copies image sources into _images/ and rewrites the <img src> to match, but it emits a :target: value verbatim as an href. Targets written as source-tree paths - "images/build_guide/x.jpeg", "../../images/build_guide/x.jpeg" - therefore resolve against the built page and 404. Audited the built HTML: 1 of 44 targets resolved before this commit, 44 of 44 after. The one that worked was ":target: _images/common_1b.jpeg", which the review had flagged as the odd one out; it was in fact the only correct one, and every other page in the manual already uses that form. Checked for basename collisions first, since Sphinx renames on collision and _images/<basename> would then be wrong. There are none on this page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
brickbots
marked this pull request as ready for review
August 10, 2026 23:42
brickbots
added a commit
that referenced
this pull request
Aug 10, 2026
* docs skill: split "turn on" from "boot" in the term table Running the style pass across all 13 manual pages exposed a fault in the term table. One row banned "boot" as a synonym for "turn on", so three agents made three different calls: software converted boot -> start, while sd_card and troubleshooting kept it and argued, correctly, that boot names the machine's own startup sequence rather than the reader's action. They are different concepts and the difference is load-bearing. "It won't boot" and "it won't turn on" are different faults with different fixes: a bad SD card lets the unit power on and then fail to boot. Two frozen headings depend on the word, so it cannot leave the manual anyway. The table now has a row for each, and section 4 explains why. Also settled "one-off": a hand-entered coordinate is a Custom Target, an entry from an observing list is an object. Found by the cross-page review of PRs #586-#598, which is the check no single-page pass can perform. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD * docs skill: record the telescope decision and its exceptions "telescope vs scope" was the one term-table row with no evidence winner (72/67 in the old manual). The maintainer has settled it: telescope. The manual is now converted, so the risk shifts from under-applying the term to over-applying it. Four things keep "scope" because they name something that is not the reader's telescope, and renaming them would be a factual error rather than a style fix: - polar scope - the sighting device inside an equatorial mount, and the Polar Alignment section is largely about aligning without one - finder scope - a separate optical finder, mentioned to contrast it with the PiFinder - SkySafari's "scope type" - a third-party field label - OTA, finder shoe, Dobsonian - fixed compounds and product names Also fixes a contradiction this exposed: SKILL.md's compact table listed OTA in the "not these" column while the reference treats it as legitimate in a parts context. The general rule now stated once: quote any interface exactly as labelled, whether it is PiFinder's or someone else's. Manual-side change is in #600. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
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.
Full simplified technical English pass over
docs/source/build_guide.rst, using thedocsskill's seven rules and approved-term table. Part of the manual-wide conversion, one PR per file.Measured change
What the converting agent reported
Content changes (added after review)
Four follow-up commits. One of them renames a heading, which this conversion
otherwise never did -- see the note below.
Quikfinder. The guide used "Quickfinder" in the section heading, its lead-in
sentence and the base-plate paragraph, while that same paragraph spelled it
"Quikfinder" twice. The two STL names were wrong as filenames, not just as
prose: the files in
case/adapters/quikfinder/arePiToQuikfinder v2 - Part 1.stland... Part 2.stl, so a reader searchingthe repo for the documented name finds nothing. The
quickfinder_base_*.jpegimage paths keep their spelling -- those are real filenames on disk.
quikfinder" links pointed at
case/adapter/quikfinder. That directory hasnever existed; the parts live in
case/adapters/quikfinder(plural) on bothmainandrelease. It is the only brokencase/link in the manual.camera"; the note called the same part "the v2.5 camera". The v2.5 build uses
the v3 camera, as
v25_upgrade.rstsays.tails or remove the ties. The step above installs those ties to hold the
battery, so removing them would undo it. Now "Snip off the loose ends of the
zip ties".
About the heading rename
Rigel Quickfinder Assembly->Rigel Quikfinder Assembly. Checked beforemaking it: no
:ref:or:doc:in the manual targetsbuild_guide:rigel quickfinder assembly-- not onmain, and not on any of the14
docs-stebranches. The only occurrence anywhere is the heading definitionitself. A nitpicky Sphinx build of this branch, and a full integration build of
all 14 branches merged together, are both clean.
verify_ste.pytherefore reports two expected failures for this PR:HEADINGS CHANGEDfor the rename, andurl LOST/url addedfor the threecorrected links. Both are deliberate.
links to itself so a reader can click for a full-size view. Sphinx copies
image sources into
_images/and rewrites the<img src>to match, but itemits a
:target:value verbatim as an href -- so targets written assource-tree paths (
images/build_guide/x.jpeg,../../images/build_guide/x.jpeg) resolve against the built page and 404.Audited the built HTML: 1 of 44 targets resolved before, 44 of 44 after.
The one that worked was
:target: _images/common_1b.jpeg, which the reviewflagged as the odd one out -- it was in fact the only correct one, and every
other page in the manual already uses that form. Checked for basename
collisions first, since Sphinx renames on collision and
_images/<basename>would then be wrong; there are none on this page.
Safety
Every other change in this PR is style only. No numbers, procedures or step order were changed.
Verified mechanically against
origin/mainthat every heading (text and underline character), every:ref:,:doc:, image path, substitution,include::and external URL is unchanged. Headings matter becauseautosectionlabelturns each one into a cross-reference target that other pages depend on, and a rename would break them silently.Sphinx builds clean under
-n(nitpicky).Any
FACT_CONCERNSabove that are not listed under Content changes were deliberately not fixed. They are reported for a maintainer decision, since changing them would be a content edit rather than a style one.🤖 Generated with Claude Code
https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD