Skip to content

docs: fix Sphinx warnings and resolve cross-references - #177

Merged
petercorke merged 6 commits into
mainfrom
docs/fix-sphinx-warnings
Nov 19, 2026
Merged

petercorke merged 6 commits into
mainfrom
docs/fix-sphinx-warnings

Conversation

@petercorke

Copy link
Copy Markdown
Owner

Cuts the normal docs build from 100 warnings to 1, and a nitpicky (-n) build from 2,317 to 265.

  • BundleAdjust scene-graph classes were documented twice; the manual copies are now :no-index: (75 warnings).
  • Fixed docstring markup: blank lines after |dtype_aliases|, the iwrite example, the mpl_styling pseudo-code and the intro.rst camera example.
  • Added a small resolver in conf.py for bare toolbox and spatialmath names, the Python intersphinx inventory, and pattern ignores for shape annotations, pgraph-relative names, OpenCV and NumPy private typing aliases.
  • Corrected matplotlib references, and removed a stray line of repeated Image links in the Kernel docstring.

The one remaining normal warning is a macOS-only clash between Image.tensor and Image.Tensor stub names. About 170 nitpicky targets remain, each a single-docstring typo, left for follow-up. Docstring and docs changes only; the test suite passes.

🤖 Generated with Claude Code

petercorke and others added 5 commits November 19, 2026 08:37
bundle-adjust.rst re-documented ViewPoint, Landmark and Observation,
which the support-classes autosummary already generates, giving 75
duplicate object description warnings. Mark the manual copies no-index.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
- ImageConstants: blank line after |dtype_aliases| so the following
  :param field is not a block-quote error (9 docstrings)
- ImageSpatial: point Kernel references at machinevisiontoolbox.Kernel.Kernel,
  removing an ambiguous cross-reference
- iwrite: the example had collapsed onto two lines; restore it
- mpl_styling: pseudo-code block is not valid Python, mark it text
- intro.rst: separate the camera example code from its printed output

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Types such as ndarray(N,2), "2-tuple" or "Vertex subclass" are split into
words and treated as class names. Ignore these pseudo-types by pattern,
cutting nitpicky warnings from 2079 to 712 and leaving the genuinely
unresolved references visible.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
- conf.py: resolve bare toolbox names (Image, PointCloud, ...) under
  machinevisiontoolbox; add the Python intersphinx inventory; ignore
  pgraph-relative names, OpenCV names and NumPy private typing aliases
- Camera, ImagePointFeatures: correct matplotlib references
  (patches.Circle, axes.Axes, lines.Line2D, Axes3D)

Nitpicky warnings: 712 to 357.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…links

- conf.py: resolve bare spatialmath names (SE3, Polygon2, ...) through the
  smtb inventory and PointCloud names under machinevisiontoolbox.PointCloud;
  ignore the undocumented CameraBase, the Dtype alias and shape names like 2N
- sources.rst, Kernel.py: link Image as machinevisiontoolbox.Image, and remove
  a stray line of repeated Image links from the Kernel docstring
- BaseFeature2D.table: plain ``str`` instead of a broken :meth: reference

Nitpicky warnings: 357 to 265.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@codacy-production

Copy link
Copy Markdown

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 7 complexity · 0 duplication

Metric Results
Complexity 7
Duplication 0

View in Codacy

NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.

@petercorke
petercorke merged commit 8f265d9 into main Nov 19, 2026
33 checks passed
@petercorke
petercorke deleted the docs/fix-sphinx-warnings branch November 19, 2026 00:31
@github-actions github-actions Bot mentioned this pull request Nov 19, 2026
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