diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 23483782..f780e8c8 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -34,9 +34,9 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v7 - - uses: actions/setup-python@v5 + - uses: actions/setup-python@v7 with: python-version: "3.12" @@ -133,13 +133,13 @@ jobs: zip -r docs/build/html/mvtb_notebooks.zip docs/notebooks - name: Upload notebooks zip artifact - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@v7 with: name: mvtb_notebooks path: docs/build/html/mvtb_notebooks.zip if-no-files-found: error - - uses: actions/upload-pages-artifact@v3 + - uses: actions/upload-pages-artifact@v5 if: github.event_name == 'push' with: path: docs/build/html @@ -155,4 +155,4 @@ jobs: steps: - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v4 + uses: actions/deploy-pages@v5 diff --git a/docs/requirements.txt b/docs/requirements.txt index 567f9a09..142b6ca3 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1 @@ -e .[docs] -sphinx-autorun @ git+https://github.com/petercorke/sphinx-autorun.git diff --git a/docs/source/conf.py b/docs/source/conf.py index d5edd3de..c563087e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -56,7 +56,7 @@ "sphinx.ext.doctest", "sphinx.ext.autosectionlabel", "sphinx.ext.inheritance_diagram", - "sphinx_autorun", + "sphinx_pyrunblock", "sphinx.ext.intersphinx", "sphinx_favicon", "sphinx_copybutton", @@ -69,8 +69,8 @@ autoclass_content = "both" # use __init__ or class docstring add_function_parentheses = False -# -- sphinx-autorun setup ---------------------------------------------------- -# options for spinx_autorun, used for inline examples +# -- sphinx-pyrunblock setup -------------------------------------------------- +# options for sphinx_pyrunblock, used for inline examples # choose UTF-8 encoding to allow for Unicode characters, eg. ansitable # Python session setup, turn off color printing for SE3, set NumPy precision autorun_languages = {} diff --git a/docs/source/image_class.rst b/docs/source/image_class.rst index fc38401a..6e793876 100644 --- a/docs/source/image_class.rst +++ b/docs/source/image_class.rst @@ -32,6 +32,7 @@ Image attributes Describe the attributes of an :class:`~machinevisiontoolbox.Image`. .. autosummary:: + :toctree: stubs :nosignatures: ~__repr__ @@ -53,6 +54,7 @@ Predicates Test attributes of an ``Image``. .. autosummary:: + :toctree: stubs :nosignatures: ~isbgr @@ -68,6 +70,7 @@ Color planes and channels Return information about the color planes of an ``Image`` instance. .. autosummary:: + :toctree: stubs :nosignatures: ~nplanes @@ -92,6 +95,7 @@ Image coordinates Describe the pixel coordinates of an ``Image``. .. autosummary:: + :toctree: stubs :nosignatures: ~contains @@ -107,6 +111,7 @@ NumPy pixel data Return ``Image`` pixel data as a NumPy array. .. autosummary:: + :toctree: stubs :nosignatures: ~array @@ -125,6 +130,7 @@ Getting pixels Access individual pixels or groups of pixels. .. autosummary:: + :toctree: stubs :nosignatures: ~__getitem__ @@ -137,6 +143,7 @@ Image datatype Describe or change the datatype of ``Image`` pixel values. .. autosummary:: + :toctree: stubs :nosignatures: ~astype @@ -161,6 +168,7 @@ Sub images Extract sub-images or planes from an ``Image`` instance. .. autosummary:: + :toctree: stubs :nosignatures: ~blue @@ -176,6 +184,7 @@ Color space and gamma Convert between color spaces and perform gamma encoding and decoding. .. autosummary:: + :toctree: stubs :nosignatures: ~chromaticity @@ -193,6 +202,7 @@ Composition Combine multiple ``Image`` instances into a single ``Image`` instance. .. autosummary:: + :toctree: stubs :nosignatures: ~anaglyph @@ -210,6 +220,7 @@ Monadic functions Operate elementwise on an ``Image`` instance and returns a new ``Image`` instance. .. autosummary:: + :toctree: stubs :nosignatures: ~abs @@ -230,6 +241,7 @@ Dyadic functions Operate elementwise on two ``Image`` instances and return a new ``Image`` instance. .. autosummary:: + :toctree: stubs :nosignatures: ~apply2 @@ -243,6 +255,7 @@ Linear filtering Linear filtering operations including convolution, corner and edge detection. .. autosummary:: + :toctree: stubs :nosignatures: ~canny @@ -266,6 +279,7 @@ Non-linear (morphological) filtering Variety of non-linear morphological operations. .. autosummary:: + :toctree: stubs :nosignatures: ~close @@ -277,7 +291,7 @@ Variety of non-linear morphological operations. ~medianfilter ~morph ~open - ~rank + ~rankfilter ~thin ~thin_animate ~triplepoint @@ -290,6 +304,7 @@ Image labeling Binary, greyscale and color image segmentation using various algorithms. .. autosummary:: + :toctree: stubs :nosignatures: ~labels_binary @@ -302,6 +317,7 @@ Image similarity Various scalar image similarity measures. .. autosummary:: + :toctree: stubs :nosignatures: ~ncc @@ -318,6 +334,7 @@ Shape changing Changing the shape of an ``Image`` instance. .. autosummary:: + :toctree: stubs :nosignatures: ~decimate @@ -336,6 +353,7 @@ Image distortion Distorting the image within an ``Image`` instance. .. autosummary:: + :toctree: stubs :nosignatures: ~interp2d @@ -353,6 +371,7 @@ Multiview operations Stereo image processing, rectification, and display. .. autosummary:: + :toctree: stubs :nosignatures: ~DSI_refine @@ -367,6 +386,7 @@ Tensor conversion Convert between ``Image`` objects and PyTorch tensors. .. autosummary:: + :toctree: stubs :nosignatures: ~tensor @@ -396,6 +416,7 @@ Arithmetic and bitwise logical operations can be performed elementwise on: .. autosummary:: + :toctree: stubs :nosignatures: ~__add__ @@ -422,6 +443,7 @@ Logical operations can be performed elementwise on: ``Image`` ☆ ``Image``. The result is always an ``Image`` with boolean pixel values: .. autosummary:: + :toctree: stubs :nosignatures: ~__eq__ @@ -443,6 +465,7 @@ Arithmetic and bitwise logical operations can be performed elementwise on: The result is always an ``Image``. A scalar value is broadcast across the whole image. .. autosummary:: + :toctree: stubs :nosignatures: ~__iadd__ @@ -464,6 +487,7 @@ A scalar value is broadcast across the whole image to create a new ``Image`` in In place stacking allows for planes to be appended. .. autosummary:: + :toctree: stubs :nosignatures: ~__imod__ @@ -473,6 +497,7 @@ Image statistics ---------------- .. autosummary:: + :toctree: stubs :nosignatures: ~max @@ -501,6 +526,7 @@ Histograms """""""""" .. autosummary:: + :toctree: stubs :nosignatures: ~hist @@ -510,6 +536,7 @@ Image moments """"""""""""" .. autosummary:: + :toctree: stubs :nosignatures: ~humoments @@ -522,6 +549,7 @@ Other """"" .. autosummary:: + :toctree: stubs :nosignatures: ~flatnonzero @@ -537,6 +565,7 @@ Region features Find homogeneous regions, text or fiducual tags. .. autosummary:: + :toctree: stubs :nosignatures: ~blobs @@ -549,6 +578,7 @@ Fiducial features ^^^^^^^^^^^^^^^^^ .. autosummary:: + :toctree: stubs :nosignatures: ~fiducial @@ -559,6 +589,7 @@ Line features Find lines in an image. .. autosummary:: + :toctree: stubs :nosignatures: ~Hough @@ -569,6 +600,7 @@ Point/corner features Find distincitive points in an image. .. autosummary:: + :toctree: stubs :nosignatures: ~AKAZE @@ -586,6 +618,7 @@ File ^^^^ .. autosummary:: + :toctree: stubs :nosignatures: ~metadata @@ -596,6 +629,7 @@ Graphical ^^^^^^^^^ .. autosummary:: + :toctree: stubs :nosignatures: ~disp @@ -606,6 +640,7 @@ Text ^^^^ .. autosummary:: + :toctree: stubs :nosignatures: ~print @@ -618,6 +653,7 @@ Comparison helpers Utilities for scalar equality checks between images. .. autosummary:: + :toctree: stubs :nosignatures: ~sameas @@ -628,6 +664,7 @@ Constant images Create images that are constant, random, or have a simple geometric pattern. .. autosummary:: + :toctree: stubs :nosignatures: ~Chequerboard @@ -648,6 +685,7 @@ Render simple graphical annotations into an image. The equivalent functions ``p from SpatialMath Toolbox create graphical overlays rather than changing the the image data. .. autosummary:: + :toctree: stubs :nosignatures: ~draw_box @@ -662,4 +700,22 @@ Test images ----------- Sometimes, for pedagogy and unit tests, it is helpful to create, process and numerically -display small example images. \ No newline at end of file +display small example images. + +Deprecated aliases +------------------- + +These names are kept for backward compatibility and will emit a deprecation warning. + +.. autosummary:: + :toctree: stubs + :nosignatures: + + ~A + ~adaptive_threshold + ~column + ~image + ~ithresh + ~ncdf + ~rank + ~thresh \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index c1c4f891..cd6582b0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -76,11 +76,11 @@ tool = ["ipython", "pygments"] docs = [ "sphinx", "pydata-sphinx-theme", - "sphinx-codeautolink", + "sphinx-codeautolink>=0.19.0", "sphinx-favicon", "sphinx-copybutton", "sphinxcontrib-programoutput", - "sphinx-autorun", + "sphinx-pyrunblock", "sphinx-design", ] diff --git a/tech-debt.md b/tech-debt.md index 790fd6e7..c9fb0440 100644 --- a/tech-debt.md +++ b/tech-debt.md @@ -34,30 +34,24 @@ warnings.warn( This is a real code change (not docs-only), so bundle it with a `fix:` commit when picked up rather than folding it into a docs-only change. -## `docs/requirements.txt` pins `sphinx-codeautolink` to an unmerged branch +## `docs/requirements.txt` pinned `sphinx-codeautolink` to an unmerged branch -Added 2026-07-29: `docs/requirements.txt` installs +Added 2026-07-29: `docs/requirements.txt` pinned `sphinx-codeautolink @ git+https://github.com/petercorke/sphinx-codeautolink.git@support-typing-self` instead of the stock PyPI release, to get `typing.Self` return-annotation resolution (needed for cross-linking chained method calls like -`Image.Random(...).print()`). This is upstream PR -[felix-hilden/sphinx-codeautolink#202](https://github.com/felix-hilden/sphinx-codeautolink/pull/202), -open and unmerged as of 2026-07-29. +`Image.Random(...).print()`) ahead of upstream PR +[felix-hilden/sphinx-codeautolink#202](https://github.com/felix-hilden/sphinx-codeautolink/pull/202) +merging. -This is the same anti-pattern that `sphinx-autorun` → `sphinx-pyrunblock` -was deliberately fixed to get away from (see git history, -2026-07-29): pinning CI to an unmerged/unpublished branch means the build -can silently break if that branch is force-pushed, rebased, or deleted. +### Resolved 2026-07-29 -**Check back around 2026-08-05** (~1 week out): if PR #202 has merged and -shipped in a `sphinx-codeautolink` release, switch -`docs/requirements.txt` back to plain `sphinx-codeautolink` (already -listed in `pyproject.toml`'s `docs` extra) and delete this entry. If it's -still unmerged, re-assess whether the pin is still worth the risk. - -(A one-time scheduled check for this is already set up — routine -`trig_019fxmj9twxENaJdfnEYGSDv`, fires 2026-08-04T23:00Z — it will report -PR/PyPI status but won't edit anything itself.) +PR #202 merged upstream and shipped in the `sphinx-codeautolink` 0.19.0 +PyPI release the same day. Verified directly (downloaded and inspected +the 0.19.0 wheel, confirmed the `Self`-handling code, rebuilt the docs +against it — chained calls now cross-link correctly). Switched +`pyproject.toml`'s `docs` extra to `sphinx-codeautolink>=0.19.0` and +dropped the git-branch override from `docs/requirements.txt` entirely. ## GitHub Actions versions are stale across most workflows @@ -141,6 +135,18 @@ annoyance: translation, and vice versa (see `~/.claude/toolbox-infrastructure.md`'s shared-infrastructure convention). +**Second live example, 2026-07-29**: PR #24 (`feat/tools-extra`, adding a +new `tool` extra to `pyproject.toml` for optional `IPython`/`pygments` +support) failed CI with `mvtbtool requires IPython and pygments, which +are not installed (No module named 'IPython')` — because `ci.yml`'s +`create-args` package list was never updated to include them. A plain +`pip install .[dev,tool]`-style CI setup would have picked up the new +extra automatically; the hand-maintained conda list requires a manual, +easy-to-forget edit in a second place every time `pyproject.toml` gains a +new extra or dependency. Patched directly (added `ipython`/`pygments` to +`create-args`) and merged 2026-07-29 — the underlying architectural gap +below is still open. + ### Fix Normalize to the same `actions/setup-python` + `pip install .[dev]`