Repository navigation
Move the documentation from Sphinx to Zensical, refresh the README and its animations - #500
Merged
Merged
Conversation
…ell outputs - Serve from /en/latest/ (site_url) so the 404 page, canonical links, and sitemap work on Read the Docs, and build into _site/ because a top-level site/ directory breaks setuptools' package discovery for editable installs. - Point Edit/View on rendered notebook pages to their docs/notebooks/ source. - Bound zensical, mkdocstrings-python, and panel (avoids a panel pre-release), pin the KaTeX and html-manager CDN versions, and key the notebook cache on library versions so upgrades re-execute notebooks. - Keep raw HTML outputs of hidden cells outside <details>, where Markdown escaped them, and collapse script-only outputs. - Strip RST literals in numpy type headers, exclude __pycache__ from the site, restore blank lines in code examples, tidy the benchmarks admonitions, and fix the logo path in example-notebook.ipynb.
…utput cards - Remove emoji from all headings, the README feature list, and the ToC summary. - 1D animation starts from zero points, adds one point per frame at first, highlights the point the learner chose last, and uses an off-center peak that a homogeneous grid cannot hit by accident. - 2D animation starts from four points. - 3D animation shows the isosurface the LearnerND learns, refining from a crude blob into a sphere inside a cut-open shell, instead of a point cloud. - Do not draw a white card in dark mode around the empty HoloViews loader output or the live_plot cancel button.
The homogeneous panels drew a fresh evenly spaced grid every frame, so all of their points moved between frames. Use the same learners with uniform_loss instead, so both panels only ever add points.
Drop the phase where points accumulate (early meshes looked like crude blobs), learn 6000 points for a smoother surface, and sway the view so the cut-away wedge stays visible.
Go back to the original look: the LearnerND plot from the "Algorithms and examples" page (plotly markers, 5000 points, a quarter cut away) with the camera orbiting it, rendered with kaleido.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Replaces the Sphinx/myst-nb documentation with Zensical (the successor of Material for MkDocs), refreshes the README, and re-renders its animations. All existing content is kept, and the old page URLs (
/tutorial/tutorial.Learner1D/,/reference/adaptive.runner.Runner/,_static/logo.png, ...) keep working.Docs build
zensical.tomlconfigures the site: light/dark/auto palette based on the logo colors, search, code copy, edit/view links, footer navigation.docs/notebooks/as jupytext MyST notebooks; the MyST roles and directives were converted to Zensical Markdown (admonitions, autorefs, snippets).docs/build_notebooks.pyexecutes them with nbclient (cached in.notebook_cache/, keyed by the source and library versions) and renders them intodocs/with their outputs embedded: HoloViews/Bokeh plots including HoloMap sliders, ipywidgets (live_info) via saved widget state, Plotly, DataFrames, images, and tracebacks. Each page also gets a downloadable.ipynb. The rendered pages are gitignored.docs/griffe_sphinx_refs.pyturns the Sphinx-style references in the docstrings (`~adaptive.Runner`) into links at build time, so the library source is untouched.readthedocs.ymlbuilds with uv and the newdocsdependency group: run the notebooks, thenzensical build --strict.Locally:
README and animations
docs/make_animations.pyrenders the README GIFs from real learner runs: 1D and 2D homogeneous versus adaptive sampling, both adding points one at a time, and the LearnerND plot from the "Algorithms and examples" page with a quarter cut away. It also renders the animated logo on the docs home page.BalancingLearner, missingSequenceLearner), no more JupyterLab extension install steps, a section on building the docs. The GIFs are referenced viaraw.githubusercontent.com/.../main, so they show up on GitHub and PyPI once this is merged.Removed
Sphinx
conf.py,Makefile, templates, the unused RTD theme JS,docs/environment.yml, and the logo notebook/script (folded intomake_animations.py).Checklist
pre-commit runon all changed filespytestpassed — the library is unchanged; the docs tooling tests pass (uv run --group docs pytest docs/ -o addopts="", 22 passed). The full suite has 7 failures intest_to_dataframethat also happen onmainwith pandas 3.0 (DataSaver.load_dataframe,adaptive/learner/data_saver.py:152).Also verified: a clean build passes
zensical build --strictwith no issues, and every page was checked in headless Chromium (light and dark mode, phone width) for rendered plots, widgets, Plotly, tables, working HoloMap sliders, and no console errors.Type of change