Skip to content

docs: fix broken code examples and stale references across the doc set - #45

Merged
keewis merged 3 commits into
GRID4EARTH:mainfrom
jmdelouis:main
Aug 31, 2026
Merged

keewis merged 3 commits into
GRID4EARTH:mainfrom
jmdelouis:main

Conversation

@jmdelouis

Copy link
Copy Markdown
Contributor

Summary

Audited every doc page against the actual source (healpix_plot/*.py) and fixed
everything that was factually wrong or would error if a user copy-pasted it.

  • plot-function.md: clarify that ax passed to plot() must be a Cartopy
    GeoAxes created with subplot_kw={"projection": ...} — a plain
    plt.subplots() axis raises AttributeError: 'Axes' object has no attribute 'set_extent'. Added a "Multiple panels side by side" example, and documented
    the previously-missing view and rgb_clip parameters.
  • mollview.md: fixed all 7 code examples importing from a nonexistent
    mollview module (from mollview import ... → from healpix_plot.mollview import ...); corrected the ellipsoid section, which claimed
    healpix_geo.nested.lonlat_to_healpix is always used (it's
    healpix_geo.ring unless nest=True).
  • sampling-grid.md: fixed the bbox example calling
    healpix_plot.SamplingGrid.from_bbox(...), which doesn't exist —
    from_bbox is a classmethod of ParametrizedSamplingGrid.
  • healpix-grid.md: added the missing zuniq caveat (as_keyword_params()
    always passes depth, which healpix_geo.zuniq.healpix_to_lonlat doesn't
    accept).
  • README.md: package name was healpix-plotting in 4 places (including
    the pip install command) vs. the real healpix-plot; fixed a dead
    #healpixgrid anchor link.
  • Aligned the Python version requirement to >= 3.11 (per pyproject.toml)
    across README.md, docs/installation.md, and mollview.md, which
    previously disagreed (3.13 / 3.13 / 3.10).

Test plan

  • grep -rn "healpix-plotting\|from mollview import\|SamplingGrid.from_bbox" docs/ README.md returns no false positives
  • Build the docs site and check the new admonitions/anchors render
  • Manually run the updated "Multiple panels side by side" example

@jmdelouis

Copy link
Copy Markdown
Contributor Author

@keewis To review ?

@keewis keewis left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks good to me, but I have two comments. The first can be a separate PR (so doesn't have to be addressed here), but the second is a very common LLM-ism comparing to the previous version that I'd just remove.

Comment on lines +38 to +45
```{warning}
This pattern does **not** work for `indexing_scheme="zuniq"`. `as_keyword_params()`
always includes `depth=grid.level`, but zuniq cell ids already encode their own
depth, so `healpix_geo.zuniq.healpix_to_lonlat` does not take a separate `depth`
argument the way `nested`/`ring` do. For zuniq data, call
`healpix_geo.zuniq.healpix_to_lonlat` directly instead of going through
`grid.operations`/`grid.as_keyword_params()`.
```

@keewis keewis Aug 31, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that's a bug in the implementation, so I'd argue we should rather improve our code. Switching from the internal dispatching to healpix_geo.auto should get us most of the way.

Comment thread docs/user-guide/sampling-grid.md Outdated
Co-authored-by: Justus Magin <keewis@users.noreply.github.com>
@keewis
keewis merged commit 42a6d04 into GRID4EARTH:main Aug 31, 2026
5 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.

2 participants