Skip to content

Conversation

@matthew-brett
Copy link
Contributor

@matthew-brett matthew-brett commented Oct 25, 2025

This is a port of the original pure Sphinx / Sphinx-gallery / ReST site to Jupyter Book 1 / sphinx-exercise / Myst Markdown.

We have deliberately stuck as closely to the original formatting as the Jupyter Book 1 conventions allow, including keeping the same tree structure and page names.

Jupyter Book 1 allows us to:

a) Get very close to the upcoming Jupyter Book 2 / Myst-MD format. We've already tested this last step to identify a few remaining incompatibilities or missing functionality, but, after this port, it will not be much work to get to Myst-MD.
b) Use sphinx-exercise as a standard format for exercises, where the exercises are drop-downs, as are the solutions.
c) Reduce code-duplication by moving much of the figure generation from separate plot_*.py files (the Sphinx-gallery idiom) either into the pages as hidden cells, or into separate notebooks, from which we abstract figures using the glue functionality.
d) Reduce complexity for authors, by making it possible to run and edit tutorials as notebooks.
e) Plumb in JupyterLite, so the user can open tutorial pages as notebook in their browser.

@matthew-brett
Copy link
Contributor Author

Built version at https://matthew-brett.github.io/scipy-lecture-notes/

Tests all passing; ready for review.

* main:
  Pin to Jupyter Book 1.
* personal:
  Revert "Switch URLs back to main site"
Now that would get us Jupyter Book 2.
@stefanv
Copy link
Member

stefanv commented Nov 17, 2025

@matthew-brett This is a HUGE amount of work! A non-trivial challenge, and I am grateful to you for taking it on 🙏

This PR covers all the major concerns I had. There are probably some smaller issues we'll identify along the way, but I'd rather we get this merged and iterate (hopefully onward towards a mystmd version!).

We have pointed several people at this PR, and there have been no comments that indicate significant concerns. I have also spoken with @bsipocz, and we have general consensus on the way forward.

So, I'll merge for now, and we'll take it from there. Thanks!

@stefanv
Copy link
Member

stefanv commented Nov 17, 2025

I also encourage others looking at this to read through the PR description and see the several benefits that already come with the port, even before switching to JBv2.

@stefanv stefanv merged commit 8854996 into scipy-lectures:main Nov 17, 2025
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

3 participants