Skip to content

Rewrite the README, fix the docs badge and the dark-mode live_info table - #502

Merged
basnijholt merged 3 commits into
mainfrom
docs/readme-rewrite
Oct 16, 2026
Merged

basnijholt merged 3 commits into
mainfrom
docs/readme-rewrite

Conversation

@basnijholt

@basnijholt basnijholt commented Oct 15, 2026 •

Copy link
Copy Markdown
Member

Description

A pass over the README and a few small docs fixes.

README:

  • Rewritten in plain prose, closer to the original README: no bold-labelled feature list, the learner list as before, and the installation and development steps kept. The "Key features" section is gone, and the docs home page no longer includes it.
  • Added a self-contained script example with BlockingRunner next to the notebook example, and a line on to_numpy()/to_dataframe().
  • Filled the gaps the old feature list left: the summary says adaptive is meant for functions of a few parameters, the learner section explains the loss function (with the built-in alternatives and the custom loss tutorial), and the executor paragraph says the runners use all local cores by default and how to pass another executor.
  • Plain pip install adaptive as the install line, with the [notebook] extra explained; the development section has the test command and a correct note on the notebook git filter.
  • Badges: the Read the Docs badge did not load as an image (readthedocs.org redirects to app.readthedocs.org), so it now uses img.shields.io/readthedocs/adaptive. Added a tests badge for the nox workflow and dropped the GitHub stars badge.
  • Removed the doctoc table of contents (GitHub shows an outline) and the TOC generator workflow that maintained it.

Docs:

  • In dark mode, the live_info table had dark rows with black text inside the white widget card, because the theme gives tables a dark background. The card now uses the light theme colors.
  • The footer no longer says "Made with Zensical" (extra.generator = false).
  • The parallelism tutorial no longer claims that Windows defaults to distributed.Client; loky is the default everywhere.

Both README examples were run: the script with BlockingRunner, and the notebook one with live_info/live_plot.

Checklist

  • Fixed style issues using pre-commit run on the changed files
  • pytest passed (docs and CSS only; uv run --group docs pytest docs/ -o addopts="" passes, and zensical build --strict reports no issues)

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • (Code) style fix or documentation update
  • This change requires a documentation update

- Restructure the README: centered logo and title, the animations right
  after a plain summary, a short feature list, a quick start with a script
  and a Jupyter example, a learner table, executors, documentation links,
  and a table of the optional extras.
- Use the shields.io Read the Docs badge; the readthedocs.org badge
  redirects and does not load as an image. Add a tests badge and drop the
  GitHub stars badge.
- Drop the doctoc table of contents (GitHub shows an outline) and the TOC
  generator workflow that maintained it.
- In dark mode, give the white widget card the light theme colors, so the
  rows of the live_info table are no longer dark.
Go back to the voice of the original README: plain sentences instead of
a bold-labelled feature list and tagline, the learner list instead of a
table, and the installation and development steps as before. The docs
home page no longer includes the removed feature list.

Set extra.generator = false so the footer no longer says
"Made with Zensical".
- Make the script example self-contained (it used peak from the
  notebook example) and show to_numpy() in it.
- Say that adaptive is meant for functions of a few parameters.
- Explain what the loss function is and point to the built-in
  alternatives and the custom loss tutorial.
- Say that the runners use all local cores by default, how to pass
  another executor, and link the parallelism tutorial.
- Install with plain pip install adaptive; the [notebook] extra adds
  live plotting and pandas for to_dataframe().
- Development: add the test command; the notebook git filter needs
  nbconvert and only matters for example-notebook.ipynb.
- Move the animation caption into the summary snippet, so the docs
  home page shows it too; label the conda downloads badge; fix the
  CQUAD link.
- Parallelism tutorial: drop the stale claim that Windows defaults to
  distributed.Client; loky is the default everywhere.
@basnijholt
basnijholt merged commit 25bf4cc into main Oct 16, 2026
18 checks passed
@basnijholt
basnijholt deleted the docs/readme-rewrite branch October 16, 2026 18:19
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