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.

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

Open
wants to merge 7 commits into
base: main
Choose a base branch
from

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 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 4 times, most recently from 48eb9a5 to 6226b82 Compare May 14, 2025 21:36
rossbar added 7 commits May 14, 2025 16:14
Result of 💾 Updating .gitignore
✅ Project already initialized with config file: myst.yml
✅ Site already initialized with config file: myst.yml.
Note: jupyter is required for myst execution engine.
- Fail if tracebacks found in myst execution log.
- Preserve log and err on traceback.
@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

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.

2 participants