Reach zero Sphinx nitpicky warnings (Rule-5 compliance) and gate in CI

[rfrenchseti]

Background

Per .cursor/rules/documentation.mdc Rule 5, the docs build must succeed with zero warnings under both:

• sphinx-build -W -b html docs docs/_build (warnings as errors)
• sphinx-build -n -b html docs docs/_build (nitpicky mode)

Today CI only enforces the first. PR #127 (Phase-10 docs reorg + Code Familiarization Plan) made substantial progress on the gap (583 → 198 nitpicky warnings) and added intersphinx + nitpick_ignore_regex for unfixable third-party / typing-internal categories, but ~198 nitpicky warnings still remain across the dev_guide and api_reference pages. This issue tracks the remaining work to reach zero and to extend CI to enforce both modes.

Top remaining unresolved targets (nitpicky run)

Count	Target	Root cause
16	nav.dataset.dataset.DataSet	:noindex: on the parent automodule:: (added to suppress duplicate-description warnings from submodules that import ImageFile) makes the class invisible to cross-references.
14	nav.dataset.dataset.ImageFile	Same root cause as DataSet.
8	nav.dataset.dataset.ImageFiles	Same.
9	NDArrayFloatType	Unqualified type-alias name in docstrings — Sphinx can't find it without a module path.
7	NavTechniqueResult	Unqualified class name in docstrings.
5	ConfidenceSpec	Unqualified class name in docstrings.
4	PSF	Unqualified class name in docstrings.
4	nav.reproj.bodies._UseMosaicLimitsSentinel	Private symbol referenced in docstrings; not exposed by autodoc.
13	nav.dataset.dataset.DataSet.pds4_* (4 attrs)	Same root cause as DataSet.
4	dict[str / tuple[str / tuple[float	Autodoc bug: malformed cross-references emitted from generic type annotations in signatures.
3	nav.nav_technique.diagnostics.BodyBlobDiagnostics.max_phase_irregularity_factor	Dataclass field that autodoc isn't documenting (likely :undoc-members: not catching it).
3	nav.nav_model.body_shape.load_body_shape	Function not exposed in autodoc inventory — needs to be in __all__ or module re-export.
...	...	(full list in PR #127 thread)

Top files with remaining warnings

Count	File	Notes
20	dev_guide_pds4.rst	References pds4.* symbols that live outside the nav API surface — needs intersphinx for pds4 package or restructuring.
16	dev_guide_reprojection.rst	Mix of BodyMosaic/RingMosaic/private helpers; reviewer flagged this in the PR-127 review.
14	dev_guide_extending.rst	Reviewer flagged NavTechnique._registry and friends here.
6	dev_guide_observations.rst	DataSet / ImageFile cross-refs blocked by :noindex:.
5	dev_guide_navigation_models_star.rst	Bare CamelCase mentions.
5	dev_guide_navigation_models_body.rst	Reviewer flagged NavModel._registry, __init_subclass__, etc.
4	dev_guide_techniques_body_blob.rst	Reviewer flagged feature-type literals.
4	dev_guide_navigation_overview.rst	Bare CamelCase mentions.
4	dev_guide_familiarization.rst	Self-introduced (PR #127).
...	...

Proposed work plan

1. Fix the nav.dataset index conflict properly (resolves ~45 warnings)

The :noindex: on automodule:: nav.dataset.dataset was added to silence duplicate-description warnings. The real cause is that dataset_pds3.py, dataset_sim.py, etc. do from .dataset import ImageFile and autodoc with :undoc-members: re-documents the imported name. Fix by either:

• Adding :no-index-entry: (Sphinx 5.2+) only on the imported members in the submodules, or
• Listing ImageFile etc. explicitly with :exclude-members: on each submodule's automodule::, or
• Setting automodule_imported_members = False in conf.py and verifying nothing was actually intended to be imported-doc'd.

Once removed, :class:nav.dataset.dataset.DataSet`` and friends resolve everywhere.

2. Apply the PR #127 reviewer findings (resolves ~30 prose violations of Rule 5)

Convert bare CamelCase / inline-literal API mentions in narrative prose to :class:/:meth:/:func:/:attr:/:data:/:mod: roles per the documentation standard. Reviewer findings list every cited file/line in PR #127 (28+ files, mostly dev_guide_*.rst). For private symbols (_registry, __init_subclass__, _abstract, etc.) either:

• Add :private-members: to the relevant api_reference automodules so the symbols become resolvable, or
• Use :role:!Symbol lookup-suppression at the prose mention.

3. Qualify type-alias / class names in source docstrings (resolves ~30 warnings)

NDArrayFloatType, NavTechniqueResult, ConfidenceSpec, PSF, Observation, NDArrayBoolType are referenced bare in numpy-style Parameters: blocks. Sphinx can't resolve unqualified names — they need either fully-qualified paths or registered intersphinx targets.

4. Expose the dataclass-field gaps (resolves ~10 warnings)

BodyBlobDiagnostics.max_phase_irregularity_factor, nav.nav_model.body_shape.load_body_shape, etc. — autodoc doesn't pick them up despite :undoc-members:. Likely need explicit .. autoattribute:: / .. autofunction:: declarations or __all__ updates.

5. Apply the Rule-2 single-space-after-period fixes

Reviewer flagged double-space after **Lead-in.** patterns in:

• dev_guide_orchestrator_ensemble.rst:167, :177
• dev_guide_techniques_body_disc.rst:252, :259
• (any other \.\*\* {2} matches across the tree)

6. Restructure docstring autodoc-rendering issues (resolves ~10 warnings)

dict[str, tuple[str, tuple[float — Sphinx is mis-tokenising generic type annotations from autodoc-rendered signatures. Investigate python_use_unqualified_type_names / autodoc_typehints settings, or restructure the offending signatures.

7. Promote nitpicky to a CI gate

Once the warning count is zero locally, extend .github/workflows/run-tests.yml to run sphinx-build -n -b html alongside the existing -W -b html step (or pass both flags together as -W -n). This makes Rule 5 enforced rather than aspirational.

Acceptance

• sphinx-build -W -b html docs docs/_build exits 0 with zero warnings
• sphinx-build -n -b html docs docs/_build exits 0 with zero warnings
• CI runs both
• PR description references this issue and links to a clean local build log

Out of scope

• Adding intersphinx for oops (no Sphinx site upstream — would need RTD setup on the upstream repo first)
• Adding new public API symbols solely to satisfy doc references; if a symbol is genuinely private, restructure the prose instead

References

• Project rules: .cursor/rules/documentation.mdc (Rule 2 single-space, Rule 5 cross-reference completeness)
• PR Core rewrite phase 10: documentation #127: Phase-10 docs reorg + familiarization plan; reduced warnings 583 → 198