Add a site-wide glossary and link its terms throughout the docs - #419
Open
miriamsr wants to merge 14 commits into
Open
Add a site-wide glossary and link its terms throughout the docs#419miriamsr wants to merge 14 commits into
miriamsr wants to merge 14 commits into
Conversation
FTC Docs already configured hoverxref for the `:term:` role, but the only glossary in the tree was the contributor-workflow one under contrib/, so nothing on the reader-facing side of the site had definitions to point at. Newcomers met "OpMode", "Control Hub", "TELEOP" and "hardwareMap" with no single place to look them up. - Add docs/source/glossary/glossary.rst: 80 entries covering the control system hardware, the programming tools, the SDK, vision, sensors and mechanisms, and competition vocabulary. Entries cross-link each other and point to the page that covers the topic in depth. Season-specific game vocabulary is deliberately left to the Competition Manual. - List it in the top-level toctree in index.rst. - Link the first mention of a term in each article to its definition: 538 `:term:` references across 129 pages. First mention only, and never on the page that explains the term itself. - Document the convention in the style guide so new content keeps using it. Nav-label text (persona pages, button-ref bodies), code blocks, literal spans, existing link and role text, and short quoted UI labels such as "Webcam 1" were left untouched. Verified with `make html SPHINXOPTS="-W --keep-going -n"`: build succeeds, every `:term:` reference resolves, and the only warning is the pre-existing intersphinx network timeout. Claude-Session: https://claude.ai/code/session_01KVJrA8GE8EGa36pDwSSxYu
The glossary page claimed the first mention of a term "usually" links back to
it. That hedge described gaps in the first pass rather than a real constraint,
so close them and make the guarantee unconditional.
- Add propagation rules for the 22 entries that had none (Blocks, Sensor,
Servo, Battery, Hub, CAD, CNC, DC Motor, Autonomous, TensorFlow, hardwareMap,
Analog Input, Digital I/O, Tournament, Fuse, IDE, FTC Docs and others), so
every entry is reachable from prose.
- Stop skipping the page that explains a term, and stop skipping contrib/,
persona_pages/ and booklets/.
- Dedupe by glossary entry rather than by name, so "Computer-Aided Design (CAD)"
links once instead of twice to the same anchor.
Total is now 1099 references across 208 pages, up from 538 across 129. A
verification pass confirms no unlinked first mention remains.
Three classes of term needed judgment rather than a pattern, and are linked
only in the sense the glossary defines:
- Match -- the competition noun follows an article or "FTC"/"Challenge"; the
verb ("a runtime that matches your environment") does not.
- Heading -- means robot heading everywhere except the contributor docs, where
it means a section heading.
- Battery -- the robot's 12V battery, never a USB power bank or phone battery.
Ten remaining occurrences read as terms but are not, and are listed explicitly
so the intent is recorded rather than rediscovered.
Also fixes a bug from the first pass: titles indented inside a directive such
as `.. only:: latex` were not recognized as titles, so a term was inserted into
the Control System booklet's title and broke its underline.
The style guide now states the always-link rule as a requirement, with a table
contrasting the FTC and ordinary-English senses of the ambiguous words, and a
list of the places that cannot hold a role at all.
Verified with `make html SPHINXOPTS="-W --keep-going -n"`: build succeeds, all
1099 references resolve, only the pre-existing intersphinx timeout warns.
Claude-Session: https://claude.ai/code/session_01KVJrA8GE8EGa36pDwSSxYu
An entry with more than one name (18 of the 80, e.g. "IMU" / "Inertial Measurement Unit") rendered its names stacked on separate lines. These cannot be joined in the source. Sphinx's glossary directive takes one term per line; writing "ADB, Android Debug Bridge" makes the comma part of a single term name, producing one anchor called "ADB-Android-Debug-Bridge" and breaking every :term:`ADB` reference on the site. Verified by building it: the comma form emits "term not in glossary" for both names. Sphinx does emit each name as its own <dt> before a shared <dd>, so join them visually with CSS instead. Each name keeps its own anchor and stays individually linkable. Note this affects HTML only -- the LaTeX/PDF build still stacks the names, since CSS does not apply there. Claude-Session: https://claude.ai/code/session_01KVJrA8GE8EGa36pDwSSxYu
The comma sat well clear of the name before it. The cause is the theme's
permalink rule:
.rst-content dl dt .headerlink { opacity:0; margin-left:.5em; ... }
Each name carries a permalink that is only made transparent when not hovered,
never taken out of the layout, so its glyph and its half-em margin reserved
space between the name and the separator.
Drop that margin for glossary terms, and render the permalink only on the last
name of an entry, so nothing sits between a name and the slash. The separator
is now a slash with equal margins on both sides.
If a browser does not support :has(), the permalink stays visible on every
name and the old gap returns -- the names still read correctly.
Claude-Session: https://claude.ai/code/session_01KVJrA8GE8EGa36pDwSSxYu
CI runs reviewdog/action-misspell with the US locale; "colour", "behaviour", "recognise" and "travelled" would have failed it. Claude-Session: https://claude.ai/code/session_01KVJrA8GE8EGa36pDwSSxYu
A camera's image sensor is not the glossary's Sensor -- a robot device on a
Hub port. Seven mentions were linked as though they were: "the webcam sensor"
on the exposure, focus, gain and pan/tilt control pages, "the camera sensor",
"the detector's array of small sensors (pixels)", and "light allowed to strike
the sensor each image frame".
Two more name a software vision processor rather than a device ("the Color
Sensor tool", "Color Sensor/Locator processors") and are also unlinked.
Found while checking a link-check failure on a file this branch had touched.
The failure itself was unrelated -- a transient 522 from javadoc.io on a URL
generated by javasphinx from javadoc_url_map, not by anything here. Both that
URL and the WhiteBalanceControl one beside it return 200 on retry.
Claude-Session: https://claude.ai/code/session_01KVJrA8GE8EGa36pDwSSxYu
# Conflicts: # docs/source/_static/css/ftc-rtd.css # docs/source/apriltag/vision_portal/apriltag_advanced_use/apriltag-advanced-use.rst # docs/source/apriltag/vision_portal/vision_multiportal/vision-multiportal.rst # docs/source/apriltag/vision_portal/vision_processor_init/vision-processor-init.rst # docs/source/apriltag/vision_portal/visionportal_camera_controls/visionportal-camera-controls.rst # docs/source/apriltag/vision_portal/visionportal_cpu_and_bandwidth/visionportal-cpu-and-bandwidth.rst # docs/source/apriltag/vision_portal/visionportal_init/visionportal-init.rst # docs/source/apriltag/vision_portal/visionportal_overview/visionportal-overview.rst # docs/source/color_processing/color-locator-explore/color-locator-explore.rst # docs/source/color_processing/color-locator-round-blobs/color-locator-round-blobs.rst # docs/source/color_processing/color-sensor/color-sensor.rst # docs/source/control_hard_compon/rc_components/power_distr/power-distr.rst # docs/source/control_hard_compon/rc_components/sensors/sensors.rst # docs/source/ftc_sdk/overview/index.rst # docs/source/manufacturing/3d_printing/filament_choice/advanced_filaments/advanced_filaments.rst # docs/source/manufacturing/3d_printing/general_knowledge/common_upgrades/common_upgrades.rst # docs/source/programming_resources/vision/webcam_controls/exposure/samples/samples.rst # docs/source/programming_resources/vision/webcam_controls/gain/ex1/ex1.rst # docs/source/programming_resources/vision/webcam_controls/gain/ex2/ex2.rst # docs/source/programming_resources/vision/webcam_controls/gain/ex3/ex3.rst # docs/source/programming_resources/vision/webcam_controls/index.rst # docs/source/programming_resources/vision/webcam_controls/overview/overview.rst # docs/source/programming_resources/vision/webcam_controls/ptz/zoom/zoom.rst # docs/source/programming_resources/vision/webcam_controls/samples/samples.rst
The glossary introduces handwheels, drivetrains, microcontroller, and Feedforward, none of which are in en_US, software-terms, or the project dictionary. Add the singular forms alongside the plurals so future pages using them don't fail the spell check.
Resolve conflicts with PR FIRST-Tech-Challenge#423 (Webcam Controls merged into VisionPortal Camera Controls) and PR FIRST-Tech-Challenge#425 (AprilTag Camera Calibration merged into Camera Calibration). Four pages this branch had glossary-linked were deleted upstream. Accept the deletions and re-apply the term links to the surviving prose in the pages that replaced them: - apriltag-camera-calibration.rst -> vision/camera_calibration/camera-calibration.rst - visionportal-camera-controls.rst, webcam_controls/index.rst -> visionportal_camera_controls/index.rst - webcam_controls/samples/samples.rst -> visionportal_camera_controls/samples/samples.rst Where upstream rewrote a sentence, tag the new wording rather than reinstate the old, and keep the branch's one-tag-per-first-occurrence convention per destination page. In programming_resources/index.rst take upstream's restructured Vision Programming section, which drops the AprilTag Programming and Camera Color Processing toctrees along with the now-deleted webcam_controls entry.
Sweep the pages that carried no glossary link at all, including the three pages PR FIRST-Tech-Challenge#423 added (Camera Controls in Blocks, Observing Controls and Webcam States), and link the first mention of each term the way the rest of the site does. Most of the pages without links turned out to need none: toctree stubs, `.. todo::` scaffolds, the 3D-printing guides (which use printer rather than FTC vocabulary), and the contrib tutorials that document how to write the docs. Those are left alone, as are the booklet wrappers, 404, todo and tos pages. Skip a term where linking it would be noise or wrong: acronyms that the site never links on their own (RC, DS), a term appearing only inside a longer term already linked on the page ("Robot Controller App"), UI labels and configuration names ("Webcam Controls", "Webcam 1"), and mentions already set in bold.
The Robot Controller and Driver Station definitions are the canonical text the rest of the site links to, so they should name the Control Hub and Driver Hub as the officially supported hardware and state that phones are legal but unsupported.
Resolves two collisions between the glossary work and upstream changes that landed after this branch was cut. decode-apriltag.rst was deleted upstream (FIRST-Tech-Challenge#428) and redirected to the AprilTag intro page. The deletion is kept, so the four glossary links on that page (AprilTag, Odometry, Webcam, OpMode) go away with it. The 3D printer recommendation update (FIRST-Tech-Challenge#405) rewrote the printer_choice pages and moved the Ender-3, AnkerMake M5C, and Bambu Lab X1C sections into a new discontinued_printers.rst. Upstream's content is taken for all four conflicted files. Two glossary links whose sentences survived are restored in place (Firmware on printer_choice, 3D Printing on high_end_printers); the other five sat on prose that moved to discontinued_printers.rst and are dropped rather than re-tagging a page upstream just added. Under the one-link-per-term-per-page convention used throughout this branch, that page would want three links (3D Printing, Firmware, Sensor) if we choose to cover it in a follow-up.
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
1 participant
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.
Closes #181.
That issue asked for a glossary that introductory and popular articles could
reference, gave "Op Mode" as a term that often goes undefined, and suggested
hoverxreffor hover-over definitions.hoverxrefwas configured inconf.pyat some point (
hoverxref_roles = ['term'],hoverxref_role_types = {'term': 'tooltip'}) but there was no reader-facing glossary for it to point at — theonly
glossarydirective in the tree is the contributor-workflow one undercontrib/. This adds the glossary and wires it up, so those settings now dosomething.
What's here
docs/source/glossary/glossary.rst— 80 entries covering control systemhardware, the three programming tools, the SDK, vision, sensors and mechanisms,
and competition vocabulary. Terms were picked by counting actual usage across
all 264
.rstfiles rather than guessed, so the list reflects what readersreally encounter. Entries cross-reference each other and link to the page that
covers the topic in depth. Listed in the top-level toctree in
index.rst.Season-specific game vocabulary is deliberately excluded and left to the
Competition Manual — it changes every year and would go stale here. The page
says so, and says the Manual wins in a disagreement.
1099
:term:references across 208 pages — the first mention of everyglossary term on every page links to its definition, and hovers to show it.
First mention only, so pages don't turn into a wall of links.
Style guide — a new Glossary Terms section under Links documents the
:term:role, the:term:encoders `` form for plurals and lowercase,and states the always-link rule as a requirement so new content keeps it.
_static/css/ftc-rtd.css— 18 entries have more than one name (IMU/Inertial Measurement Unit). Sphinx's glossary directive needs one term perline for each name to get its own anchor, so a few lines of CSS render the
names on a single slash-separated line.
Judgment calls worth reviewing
Three glossary words are also ordinary English, and are linked only in the
sense the glossary defines:
verb ("a runtime that matches your environment") does not.
means a section heading.
battery.
Ten further occurrences read as terms but aren't (
"check for a match with the DS app version","Anker Battery Pack") and are left unlinked.Text that cannot hold a role is untouched: code blocks and literals, existing
link text,
:alt:text, section titles, andbutton-reflabels / card headers(a link nested in a button doesn't render).
Verification
make html SPHINXOPTS="-W --keep-going -n"— succeeds; all 1099 referencesresolve (an unresolved
:term:is a warning, so this is a real check). Theonly warning is a pre-existing intersphinx timeout to sphinx-doc.org.
make imagecheck— passes (no images added).make rediraffecheckdiff— passes (files added, none moved or renamed).Not run locally:
make latexpdfandmake booklets. Worth noting the CSSabove is HTML-only, so the PDF still stacks alternative names on separate
lines. Everything else applies to both.
https://claude.ai/code/session_01KVJrA8GE8EGa36pDwSSxYu