Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Add Myst (new tech stack) workflow #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 10 commits into
base: main
Choose a base branch
from
Open

Add Myst (new tech stack) workflow #50

wants to merge 10 commits into from
+176 −1

Conversation

rossbar
Copy link
Member

@rossbar rossbar commented May 13, 2025

Simplest possible setup (with minimal instructions) for getting up and running with myst.

@rossbar rossbar force-pushed the myst branch 2 times, most recently from 05fd475 to f66517d Compare May 14, 2025 17:07
bsipocz
bsipocz reviewed May 14, 2025
View reviewed changes
@bsipocz bsipocz force-pushed the myst branch 3 times, most recently from 613fb20 to eab84c9 Compare May 14, 2025 18:03
@rossbar rossbar force-pushed the myst branch 5 times, most recently from 7ffe938 to 1e5d169 Compare May 14, 2025 23:14
@rossbar
Copy link
Member Author

rossbar commented May 15, 2025

One (of the many) goals of this project I think should be to serve as a "transition guide" from the existing myst-nb/sphinx stack to the mystmd stack. Here are some quick takeaways from comparing workflows:

Massive improvement (IMO)

  • The decoupling of site layout from source layout is a huge improvement over the sphinx workflow. The ability to explicitly specify site layout in the myst.yml config file is a really nice feature, and eliminates one of the most common pain points with trying to get toctree(s) to give you the site layout you want. In my experience at least, this is an excellent new feature.
    • In principle it's also possible to envision having multiple possible layouts for a site. E.g. @danielballan expressed the desire for using the same source material to lead workshops for two different audiences; say one hardware-focused and one data-analysis focused. Since the config file is the source of truth for site layout, all that should be required is modifying/maintaining multiple site layout configs without ever having to touch the source material.

Needs

  • A way to preview the site in CI - with the sphinx-based toolchain, we rely entirely on the fact that the site produced by sphinx is a pure static site that doesn't require any special hosting/web assets. This enables the pattern where we can push the build products (_build/html) uncompressed up to a bucket, then simply open a link to that URL in the browser to get the site preview. The discussion along these lines is captured in Add a myst preview subcommand jupyter-book/mystmd#2017.
  • A few more hooks into the notebook execution - specifically, a way to escalate notebook execution errors to myst build errors. To be clear, the story isn't that great on the sphinx-side either: we currently rely on -WT --keep-going to get the behavior we most want (escalate warnings to exceptions, give full tracebacks, and continue executing the other notebooks) but this isn't perfect because the -W encompasses all sphinx warnings. We'd definitely want to have a way to continue treating myst build warnings/errors separate from notebook execution warnings/errors. See also Improve the execution experience in MyST jupyter-book/mystmd#2019

@bsipocz
Copy link
Member

bsipocz commented May 28, 2025

Can we merge this? I mean even without the CI preview I feel this is a great addition, so no need to wait for the PR to develop some code-rot.

bsipocz
bsipocz approved these changes May 28, 2025
View reviewed changes
Copy link
Member

@bsipocz bsipocz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs a rebase obviously, but content-wise, let's have this in!

bsipocz
bsipocz requested changes May 28, 2025
View reviewed changes
Copy link
Member

@bsipocz bsipocz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, well, I was overly enthusiastic, as the landing page still needs some TLC to look more like the page with the old stack.

E.g. I would even go as far as to say myst forcing the first toc item to be a file: is rather inconvenient here (and was also in my other repo)

stefanv
stefanv reviewed Jul 15, 2025
View reviewed changes
README.md
for example::

```bash
firefox _build/html/index.html
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this load the JS bundles as well? I expect CORS to cause trouble, so that you need a simple static server, like python -m http.server (I prefer a multi-threaded server script, but you get the idea).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is with the build with sphinx section.

I'm fairly certain it's a practically garbage page when opened up after a a myst build.

@rossbar @bsipocz
Add myst config.
2356b5c 
Result of 💾 Updating .gitignore
✅ Project already initialized with config file: myst.yml
✅ Site already initialized with config file: myst.yml.
@rossbar @bsipocz
Flatten toc in myst.yml.
836b178
@rossbar @bsipocz
Add dependencies for myst stack.
cc46816 
Note: jupyter is required for myst execution engine.
@rossbar @bsipocz
Add basic myst/sphinx site building instructions to README.
68a8529
@rossbar @bsipocz
Add a myst-build job to ci workflows.
68adb70 
- Fail if tracebacks found in myst execution log.
- Preserve log and err on traceback.
@rossbar @bsipocz
Undo .gitignore munging from myst init.
2634551
@rossbar @bsipocz
Fixup rebase bork.
70d9747
bsipocz
bsipocz approved these changes Sep 7, 2025
View reviewed changes
Copy link
Member

@bsipocz bsipocz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have added a new landing page for JB2, for now I think we should go ahead and merge this PR and eventually consolidate the two landings into one (and add execution to the rendering, etc.)

But all of that can be done in a follow-up, no need to hold this back any longer.

@bsipocz
Copy link
Member

bsipocz commented Sep 7, 2025

The pixi-based jobs are known to be broken (#73) and fixing them is beyond scope here.

@bsipocz
Copy link
Member

bsipocz commented Sep 7, 2025

@rossbar - please go ahead with the merge if/when you are happy with the changes.

@bsipocz bsipocz added the type: Enhancement New feature or request label Sep 7, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@stefanv stefanv stefanv left review comments

@danielballan danielballan danielballan approved these changes

@bsipocz bsipocz bsipocz approved these changes

Assignees
No one assigned
Labels
type: Enhancement New feature or request
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@rossbar @bsipocz @stefanv @danielballan