Skip to content

Let a reader run the notebook without installing anything - #11

Merged
DenisDrobyshev merged 1 commit into
mainfrom
add/open-in-colab
Sep 20, 2026
Merged

DenisDrobyshev merged 1 commit into
mainfrom
add/open-in-colab

Conversation

@DenisDrobyshev

Copy link
Copy Markdown
Member

Every module linked its notebook to a GitHub blob page. That renders the code and will not run it. To try anything, a reader had to clone the repository, install Python, install the requirements and start Jupyter — a barrier in front of all twenty-seven modules of a course whose argument is that you should check a claim yourself rather than believe it.

Why this is free

The notebooks import NumPy and Matplotlib and nothing else — the rest is the standard library, checked across all 27:

numpy 27, matplotlib 27, csv 1, collections 1, math 1, re 1

Both are already in Colab. So the link costs nothing to offer and nothing to install: click, and it runs. prerequisites.md has been recommending Colab for parts III–VI all along; there was just no way to get there.

The order matters

The Colab link comes first, the filename second:

Ноутбук: открыть в Colab · notebooks/01-claim-baseline-noise.ipynb

Rendered the other way round it was the last item on a dense metadata line and wrapped onto a line of its own — the least prominent thing on the page, while being the most actionable. I checked this in the built site rather than guessing.

Keeping it true

scripts/check_modules.py (standard library only) requires that every module page carries both links in that shape, that every referenced notebook exists, and that every notebook is reachable from some page.

None of that is covered today: mkdocs --strict does not check outbound links, and the notebook job proves the files execute, not that a reader can find them. Verified the check fails on each case — a missing Colab link, a page pointing at a notebook that is not there — and passes on the tree as it stands.

Verified

  • 54 pages updated (27 modules × 2 languages), all pass the new check
  • mkdocs build --strict clean
  • All 27 notebooks fetchable at the URL Colab reads from — raw.githubusercontent.com returns 200 for every one
  • The Colab URL shape resolves

Every module linked its notebook to a GitHub blob page. That renders the code
and will not run it: to try anything the reader has to clone the repository,
install Python, install the requirements and start Jupyter. That barrier stood
in front of all twenty-seven modules of a course whose whole argument is that
you should check the claim yourself rather than believe it.

The notebooks import NumPy and Matplotlib and nothing else -- the rest is the
standard library -- and both are already in Colab. So the link costs nothing to
offer and nothing to install: click and it runs. The prerequisites page has been
recommending Colab for parts III to VI all along; now there is a way to get
there.

The Colab link comes first and the filename second, because the verb is what
the line is for. Before the reorder it was the last thing on a dense metadata
line and wrapped onto its own, which is where a reader's eye goes least.

scripts/check_modules.py keeps it true: every module page must carry both links
in that shape, every referenced notebook must exist, and every notebook must be
reachable from a page. mkdocs --strict checks none of that -- the links are
outbound -- and the notebook job only proves the files execute, not that anyone
can find them.
@DenisDrobyshev
DenisDrobyshev merged commit 4c303b2 into main Sep 20, 2026
5 checks passed
@DenisDrobyshev
DenisDrobyshev deleted the add/open-in-colab branch September 20, 2026 14:03
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