docs(troubleshooting): put the condition first in the GPS lock note

[brickbots]

Why

The note closing "The GPS never locks" was read two different wrong ways on Cloudy Nights (thread 914101, 2026-09-10). One reader took it as "GPS is only for the solar system", another called the wording confusing twice.

The sentence opened with "a GPS lock is not needed" and hung the whole condition on a trailing "once your location and time are set". A reader in a hurry keeps the first half and drops the second, which is exactly the misreading that happened.

What changed

One note in docs/source/troubleshooting.rst. The condition now comes first, and the two cases are separate.

Before

A GPS lock is not needed to focus, align, or push to objects once your location and time
are set. It is needed before the Planets and Comets catalogs fill in, because those
depend on your time and place.

After

Push-To and the Planets and Comets catalogs need a location and a time. They do not
need the GPS receiver to supply them. Entering your location and time by hand works
just as well as a lock. With no lock and nothing entered by hand, Push-To shows
Searching for GPS in place of directions, and the two catalogs stay empty. The
Focus and Align screens work either way, because neither depends on where or when you
are.

Naming Push-To in the first sentence, alongside the catalogs, is what closes off the "GPS is only for the solar system" reading. The reader is also told what they actually see on screen when nothing is set, which is the job of a troubleshooting page.

The paragraph above it already points at :ref:user_guide:place & time``, so the note no longer repeats that imperative. It states the consequence instead.

Facts checked against the code

The issue's framing was mostly right, with one correction.

• SharedStateObj.altaz_ready() is location.lock and datetime() (python/PiFinder/state.py:332). That single flag gates everything location-dependent.
• Entering coordinates by hand sends Location.make_fix(lat, lon, alt, "MANUAL"), which sets lock: True (python/PiFinder/ui/callbacks.py:337, python/PiFinder/state.py:225). A hand entry is therefore equivalent to a lock, not a lesser substitute.
• aim_degrees() returns (None, None) unless location.lock and dt (python/PiFinder/calc_utils.py:195). This holds for EQ mounts too, even though the maths would not require it. Push-To genuinely does not work without a location and a time.
• object_details.py:445 draws "Searching" / "for GPS…" in place of the pointing instructions when altaz_ready() is false. That is the message quoted in the note.
• PlanetCatalog and CometCatalog are the only catalogs whose positions are computed at runtime (python/PiFinder/catalogs.py:994), and both gate on altaz_ready().

Correction to the issue. Issue #646 lists alignment among the things that stop working with neither a lock nor a manual entry. The code says otherwise. align_on_radec() asks the solver for the camera pixel matching an RA/Dec and stores it as target_pixel (python/PiFinder/ui/align.py:27). No location, no time. align_daytime.py has no location reference either. Location is used on the Align screen only to rotate the star chart, and that already degrades gracefully to north-celestial-pole-up, as user_guide.rst documents. The Focus screen (python/PiFinder/ui/preview.py) has no location or time dependency at all, and solver.py references neither.

So the note says Focus and Align work either way, rather than repeating the issue's claim.

Out of scope, worth a follow-up

Three things turned up while checking the facts. None of them belongs in this diff.

1. catalogs.rst is imprecise the same way the old note was. docs/source/catalogs.rst says of both Comets and Planets: "The catalog fills in once the PiFinder has a GPS lock." By the same altaz_ready() logic that is imprecise, since a hand-entered location fills them just as well. Left alone to keep this diff to the one note.

2. EQ push-to is over-gated (code, not docs). aim_degrees() guards its EQ branch on location.lock and dt, but that branch is pure RA/Dec subtraction of two solve-frame values (calc_utils.py:212-234). It needs neither a location nor a time. ui/object_details.py:446 gates the whole screen the same way. An EQ user with a good solve and no GPS sees "Searching for GPS" where the answer is computable. The note documents the shipped behaviour, which is correct for the manual, but this is worth its own issue.

3. Two guards test the wrong thing (code, not docs). integrator.py:493 and calc_utils.py:243 guard on location is None / if location, but shared_state.location() never returns None — it returns an unlocked Location() at lat 0, lon 0 (state.py:295). Any path that sets a datetime without a lock (the web time_lock at server.py:1458, telemetry replay, the console debug key) makes these compute alt/az at Null Island. The altaz_ready() gates further up currently mask it, so there is no user-visible symptom today, but the guards are wrong as written.

Also not in the note, deliberately. Polar Align, observation logging, Save Location and the zenith-up chart orientation all depend on altaz_ready() too. The note stays scoped to what issue #646 asked about, and it does not claim to be an exhaustive list. "The Focus and Align screens" is accurate as written: Polar Align is a separate menu item (ui/menu_structure.py:1254) from Align (:55).

Verification

python -m sphinx -b html -n -q source /tmp/sphinx_646

Prints nothing, so the manual still builds with zero warnings.

git diff -U0 -- docs/source | grep '^+' | grep -nE '—|;'

No hits. The added text carries no em-dashes or semicolons, uses the approved terms, and matches the file's two-spaces-after-a-full-stop convention.

Closes #646

🤖 Generated with Claude Code

[brickbots]

Follow-up commit ad880e8d extends this to catalogs.rst.

Both the CM and PL entries said the catalog fills in "once the PiFinder has a GPS lock" — imprecise in exactly the way this PR is about, since a hand-entered Place & Time fills them just as well (Location.make_fix(..., "MANUAL") sets lock=True and is indistinguishable downstream). Rewritten to lead with what the catalogs actually need, and cross-referenced to user_guide:place & time.

Build stays clean at zero warnings; both new :ref:s resolve to user_guide.html#place-time in the built HTML.