Skip to content

docs: migrate to Zensical, refresh catalog - #165

Merged
tlambert03 merged 35 commits into
pyapp-kit:mainfrom
tlambert03:docs/zensical
Oct 19, 2026
Merged

tlambert03 merged 35 commits into
pyapp-kit:mainfrom
tlambert03:docs/zensical

Conversation

@tlambert03

@tlambert03 tlambert03 commented Oct 17, 2026 •

Copy link
Copy Markdown
Member

Moves the docs from MkDocs to Zensical and gives the colormap catalog a pretty big refresh.

Build and hosting:

  • two-step build: python docs/_gen_catalog.py, then zensical build. .readthedocs.yaml is updated to match
  • the docs workflow now only checks that the build passes, and no longer deploys to GitHub Pages (Pages should be turned off after merging, so we're only serving from RTD)
  • the site is a lot lighter (about 208 MB → 50 MB). colormap pages are no longer listed in the sidebar... they're reached from the catalog, category and collection pages, and from search (with breadcrumbs)

Catalog:

  • filter by name, collection, category and monotonic lightness, and the filters are kept in the URL so you can share them
  • a page per collection (e.g. all of crameri), plus a collections index
  • charts and test images are drawn in the browser rather than baked into each page:
    • color vision deficiency simulation (buttons marked with the missing cone, L / M / S)
    • sine ramp on continuous maps, plus a circular sine ramp (cyclic) and peaks (diverging)
    • discrete maps get one lightness point per color and no sine ramp
  • the snippet tabs on each colormap page are cmap / matplotlib / plotly / napari / CSS / More... (with a short example for altair, bokeh, vispy, pygfx, pyqtgraph and Earth Engine). every example was run against current releases, except Earth Engine, which needs an account. the old napari example used napari.view_image, which is gone in napari 0.9... it now uses napari.imshow

New compare page:

  • up to six colormaps side by side: colorbars, sine ramps and a lightness chart, with CVD simulation and a shareable URL
  • lines get distinct dash patterns, and there's a toggle to color them with a fixed categorical set (petroff6) instead of the colormaps themselves
  • you can pick, drop or paste your own image (it never leaves the browser) and see it in grayscale and through each colormap. two samples: a cat (mine), and elevation around Corsica (NOAA ETOPO 2022, CC0) with sea level at the middle, for diverging maps

Other stuff:

  • dark theme by default
  • pydantic docs and tests use v2 forms
  • cmap._util.report() derivatives now use np.gradient, so they no longer start with a padded zero
  • __all__ is reordered so the API page leads with Colormap and Color
  • Kovesi links moved to Codeberg, and a typos pre-commit hook (fixed the typos it found)

RTD preview: https://cmap-docs--165.org.readthedocs.build/en/165/

🤖 Generated with Claude Code

tlambert03 and others added 7 commits October 17, 2026 18:27
- Build with zensical instead of mkdocs + mkdocs-material. MkDocs hooks and
  gen-files are replaced by a pre-build step (`docs/_gen_catalog.py`) and the
  zensical macros extension (`docs/_macros.py`).
- Catalog sidebar now lists categories (with new per-category pages) instead
  of every colormap, which shrinks colormap pages from ~340 KB to ~30 KB and
  the built site from ~208 MB to ~46 MB.
- Catalog grid: filter by name/alias, source and monotonic lightness.
- Colormap pages: CVD simulation now applies to the colorbars and sine ramp
  (rendered client-side), charts follow the light/dark theme, code tabs for
  matplotlib/napari/CSS, prev/next links and a "compare" button.
- New compare page with shareable URLs.
- Relative links throughout, so the GitHub Pages copy (served under /cmap/)
  works too. Absolute catalog links in colormap `info` are rewritten.
- Chart.js 4.1.2 -> 4.5.1; drop the Material Icons font, unused chart data,
  and unused docs dependencies (colorcet, imageio).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The separator carried over from mkdocs.yml breaks zensical's search worker
("Search is unavailable").

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Exclude code tabs, chart sections, the pager and catalog grids from search
(colormap pages themselves stay indexed). search.json: 1.3 MB -> 380 KB.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Rendered client-side like the sine ramp, so they follow the CVD toggle.
Ported from Kovesi's circlesineramp.m and MATLAB's peaks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…efault

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Oct 17, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.73%. Comparing base (ea766cf) to head (3f186bf).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #165      +/-   ##
==========================================
+ Coverage   94.62%   95.73%   +1.11%     
==========================================
  Files         168      168              
  Lines        2232     2228       -4     
==========================================
+ Hits         2112     2133      +21     
+ Misses        120       95      -25     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

tlambert03 and others added 22 commits October 18, 2026 11:05
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- canonical urls point at /en/stable/; remove 'edit this page'
- breadcrumbs on colormap pages; fix prev/next pager layout
- alphabetical 'All' catalog; leaner search entries for colormap pages
- deep purple accent in light mode (pink fails contrast on white)
- installation, quick start and 'mapping data to colors' docs
- minify css/js, watch src, svg favicon, fix data cache key
- fix typos and add the typos pre-commit hook

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ormap

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tips

- compare: dash pattern per line, gradient lines, optional petroff6 colors,
  explicit 6-map limit
- category intros, 'All collections', non-sticky filter on small screens
- named colors: aliases share a box, contrast-based text, no clipping
- API page in __all__ order (most important first)
- higher-contrast pills; tidier colormaps page examples; subtler
  external-link arrow; solid tooltip swatches

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Zensical's tooltips also open on focus, and clicking a label focuses its input,
so put the titles on the labels' text instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t derivative axis

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Use np.gradient (same length as x, one-sided at the ends) instead of np.diff
padded with a leading 0, and differentiate with respect to x itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- catalog/collections/: an index of collections, and a page for each with its
  license, authors and source, and its colormaps
- colormap pages link to their collection
- catalog filters are read from and written to the URL
  (?q=&collection=&category=&monotonic=1)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tlambert03 and others added 6 commits October 19, 2026 13:17
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…compare page

The compare page gets an Image section: pick, drop or paste an image (it stays
in the browser), and it's shown in grayscale and through each colormap, with
the CVD simulation. Two samples: a cat (photo by Talley Lambert), and
elevation around Corsica for diverging colormaps.

corsica.png is from NOAA NCEI's ETOPO 2022 15 Arc-Second Global Relief Model
(CC0-1.0, https://doi.org/10.25921/fd45-gt74):

  https://coastwatch.pfeg.noaa.gov/erddap/griddap/ETOPO_2022_v1_15s.csv?z[(41.2):1:(43.2)][(8.0):1:(10.2)]

flipped north up and scaled as round(255 * (0.5 + z / (2 * max|z|))), so that
sea level is the middle value.

Also: sticky colormap input and CVD pills, and Colorbars / Image / Lightness
headings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The snippet tabs on each colormap page are now cmap, matplotlib, plotly,
napari, CSS and More..., with a short example for each of altair, bokeh,
vispy, pygfx, pyqtgraph and Earth Engine. The napari example used
`napari.view_image`, which no longer exists (napari 0.9): it now uses
`napari.imshow`.

Also: hide the name label on the colorbars of a colormap's own page, and fix
the pygfx return type in colormaps.md (a TextureMap).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tlambert03
tlambert03 enabled auto-merge (squash) October 19, 2026 13:40
@tlambert03
tlambert03 merged commit 19853c3 into pyapp-kit:main Oct 19, 2026
22 checks passed
@tlambert03
tlambert03 deleted the docs/zensical branch October 19, 2026 13:43
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