Skip to content

docs(quick_start): split Configuration Setup into rotate, set type, and a reference - #651

Merged
brickbots merged 2 commits into
mainfrom
docs/quickstart-config-split-648
Sep 23, 2026
Merged

brickbots merged 2 commits into
mainfrom
docs/quickstart-config-split-648

Conversation

@brickbots

Copy link
Copy Markdown
Owner

Quick Start step 4 covered five topics in one continuous passage. This splits it into the three-part shape #648 asks for, without moving or renaming the section itself.

New structure

Configuration Setup (unchanged, still --underlined) now contains three ^-underlined sub-sections, matching the heading ladder the page already uses under "First Time Out":

  • Rotating the Body — the rev4_convert.gif, the spring-loaded detents, and a pointer to the reference below for readers who don't yet know which position they want.
  • Setting the PiFinder Type — why the software needs to know, the prose menu chain ("From the main menu, select Settings, scroll down to Advanced, then select PiFinder Type"), and the three existing screenshots.
  • PiFinder Type Entries — a short reference: Rev4 Left / Right / Straight, the Straight-vs-rotate guidance, AS Bloom / AS Heart, and the existing v3 / v2.5 .. note::.

A short paragraph stays directly under the section heading to frame it as two steps.

Cross-references

Inbound :ref:s to quick_start:configuration setup still resolve. The heading text and its level are unchanged, so the label is untouched. Verified in the built HTML that all four still point at a real #configuration-setup anchor:

  • docs/source/troubleshooting.rst:216
  • docs/source/troubleshooting.rst:311
  • docs/source/software.rst:72
  • docs/source/quick_start.rst:280 (the Mounting note, in-page)

The three new sub-sections add quick_start:rotating the body, quick_start:setting the pifinder type and quick_start:pifinder type entries. None collides with an existing heading on the page.

Facts checked against the code

Verified the option list and its on-device labels in python/PiFinder/ui/menu_structure.py. Two corrections to the previous prose:

  • It said "The rev4 entries sit at the bottom of the list. Three of them name the position...", implying there are more than three. There are exactly three: Rev4 Left, Rev4 Right, Rev4 Straight.
  • The note said "The entries above these are the v3 and v2.5 configurations." The entries immediately above the rev4 group are AS Bloom and AS Heart. The v3 / v2.5 configurations are the five at the top of the list (Left, Right, Straight, Flat v3, Flat v2), which is how the note now reads.

Also added a sentence about the "Options for DIY PiFinders" message that Advanced shows for two seconds on open (callbacks.show_advanced_message). A ready-built owner following this route hits it and can read it as a wrong turn, which is close to the Discord report in the issue.

No screenshots were re-taken. The three existing images are already at the rev4 352x352 size and still show the right screens.

Verification

python -m sphinx -b html -n -q source /tmp/sphinx_648 prints nothing (exit 0). The added lines contain no em-dashes or semicolons, and match the page's one-space-after-full-stop convention.

Closes #648

🤖 Generated with Claude Code

brickbots and others added 2 commits September 22, 2026 17:02
…nd a reference

Configuration Setup covered five topics in one continuous passage: rotating
the rev4 body, the PiFinder Type setting, the three rev4 positions, the
Analog Sky entries, and the v3 / v2.5 note.  Readers on Cloudy Nights and
Discord asked for it to be broken up, and a new rev4 owner could not find
PiFinder Type from the step as written.

Split it into three sub-sections under the existing heading: Rotating the
Body, Setting the PiFinder Type, and PiFinder Type Entries.  The heading
"Configuration Setup" and its level are unchanged, so the inbound :ref:s
from troubleshooting.rst and software.rst still resolve.

Also corrected against menu_structure.py: there are exactly three rev4
entries, and the entries immediately above them are AS Bloom and AS Heart,
not the v3 / v2.5 configurations, which are the five at the top of the list.
Noted the "Options for DIY PiFinders" message that Advanced shows on open,
since it reads as a wrong turn to a ready-built owner.

Closes #648

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The three screenshots for "select Settings, scroll down to Advanced,
then select PiFinder Type" skipped the middle step: settings_select.png
shows the main menu and settings_menu_config.png is already titled
Advanced, so nothing showed Advanced highlighted within Settings.  That
is the step the Discord report lost, since Advanced sits below the fold
and needs six DOWN presses to reach.

The images now map one to one onto the three steps of the prose chain.
Captured at rev4 176x176 with the battery monitor on, so the title bar
matches its neighbours, then run through screenshot_to_doc.py.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@brickbots

Copy link
Copy Markdown
Owner Author

Follow-up commit 21d365b3 adds the missing middle screenshot.

The three images for "select Settings, scroll down to Advanced, then select PiFinder Type" skipped a step: settings_select.png shows the main menu and settings_menu_config.png is already titled Advanced, so nothing showed Advanced highlighted within Settings — the step the Discord report lost. It sits below the fold and takes six DOWN presses to reach.

settings_advanced_select.png captured at rev4 176×176 with the battery monitor on so the title bar matches its neighbours, then run through screenshot_to_doc.py (352×352, house amber tint). The images now map one-to-one onto the three steps of the prose chain.

@brickbots
brickbots merged commit ab22e0e into main Sep 23, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant