Let a reader run the notebook without installing anything - #11
Merged
Merged
Conversation
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.
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
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.
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:
Both are already in Colab. So the link costs nothing to offer and nothing to install: click, and it runs.
prerequisites.mdhas 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:
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 --strictdoes 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
mkdocs build --strictcleanraw.githubusercontent.comreturns 200 for every one