2022#
April#
Atending#
Matthew McKay / ANU / mmcky
Rowan Cockett / Curvenote / rowanc1
Chris Sewell / EPFL / chrisjsewell
Chris Holdgraf / 2i2c / choldgraf
Damián Avila / 2i2c / damianavila
Aakash Gupta / ANU / aakashgc
Notes#
myst-spec
- @fwkoch, @rowanc1, @chrisjsewellover the past month, we’ve put together a language-agnostic repo of JSON schema types for the MyST AST nodes, building on existing
mdast
types.This also includes test cases, similar to the commonmark spec, which may be used to validate implementations of the spec
mystjs
, the markdown-it javascript implementation, already consumes myst specunified-myst
, the new unified ecosystem implementation, will also be “spec compliant”!python side hasn’t been adressed quite yet.
-
There are some drawbacks of markdown-it
It doesn’t have a well specified AST
myst-spec uses
mdast
, but that’s a “unified ecosystem” thing, not a markdown-it thing
Unified ecosystem has their own parser called micromark (and that is bundled in remark)
The unified-myst parser uses this framework instead of markdown-it
Q: What’s the relationship between all of these parsers?
MyST-js would use the unified parser
VSCode uses markdown-it-docutils (not even mystjs)
Unified ecosystem is well-maintained with many extensions
Q: how do all of these pieces fit together for the end-user experience?
We should have a strategy meeting about the direction of these pieces so that we can align on a path forward.
There is not currently a “product” at the end that is driving all of this forward (from an end-user’s perspective).
Q: This seems like a lot of stuff to maintain. How can we sustain our efforts?
We have a bunch of stuff we’ve added to grow our maintenance burden.
Can we tie the JS myst stuff to end-users in a way that we can fund?
General agreement that we need a better story around the strategy and maintainability of this stack.
Product strategy meeting?
Bring in multiple stakeholders around a “product vision / strategy” for where the ecosystem could move going forward.
Could we bring the learnings from the JS world back into the Python world to improve Jupyter Book.
Curvenote renderer for multiple composable “JupyterBooks”
Hosting a conference at end of April!
CH: New book theme is out, will update Jupyter Book to use it soon!
Note: we did not get to the following topics, but there are some notes
Gated Directives (sphinx-exercise). There has been some comments and interest in making this syntax more general so it could be used for other directives.
Best Strategy? As an extension?
Mention this with work being done on
myst-spec
First Developer Interview: “Deep Dive into Parsing” (with Chris Sewell)
cover myst-parser, markdown-it-py
Any questions? Please add it to the issue.
Will post a recording to share more widely.
JupyterLab Myst Extension as you go
Editing experience in jupyter is very critical!
MyST Docs
New repository? Migrate and refurbish content?
March#
Attending#
Matt McKay / Australian National University / mmcky
Rowan Cockett / Curvenote / @rowanc1
Chris Sewell / EPFL / @chrisjsewell
Franklin Koch / Curvenote / @fwkoch
Chris Holdgraf / 2i2c / @choldgraf
Damián Avila / 2i2c / @damianavila
Will Lachance / Voltus / @wlach
Short updates#
mystjs initial release!
And many other PRs updates in the JS world (e.g. docutils state, packaging)
release of myst-parser v0.17.0 (https://myst-parser.readthedocs.io/en/latest/develop/_changelog.html), jupyter-cache v0.5.0 (https://jupyter-cache.readthedocs.io/)
Both feed into executablebooks/MyST-NB#380
soon-to-be-released sphinx-book-theme (v0.3). in pre-release now but haven’t gotten any negative feedback. executablebooks/sphinx-book-theme
sphinx-togglebutton also released w/ smaller footprint: executablebooks/sphinx-togglebutton
Notes#
mystjs / myst-spec discussion (@rowanc1)#
Functionality, demo, myst “spec”, reflections and thoughts on next steps!
Slides: https://docs.google.com/presentation/d/1lLJUgILhBAZeLyUXucHtQGsA9OjqlSoIjop5_bFVTWg/edit
Questions to answer
Should MyST exist as a first-class project within Executable Books?
General yes
Where should its “project” documentation live?
myst.tools
?spec.myst.tools
?Agree to do this
Chris H will get the domain (UPDATE: Chris got the domain, now we just need to point something to it).
Figure out the following two later:
python.myst.tools
-> myst-parser docs? (maybe we rename tomyst-python
)js.myst.tools
->mystjs
docs?No decisions made here, we’ll get to it later.
How do we avoid duplicating a bunch of documentation etc.
Define the core myst spec in a single repo, along with implementation-agnostic syntax
Unit tests of the spec - where do they live?
Use
chrisjsewell/myst-spec
for this?Generally agree this is a good place to do it, need to consolidate docs somehow.
myst-spec: https://myst-spec.readthedocs.io
Did a quick demo of the spec to compare w/ mystjs
myst-nb / embedding code outputs (@chrisjsewell)#
executablebooks/MyST-NB#380 is basically ready to go apart from this
Perhaps merge, then work on this separately?
Developer interviews (@mmcky)#
I will be coordinating a series of developer interviews (recorded via Zoom) on a range of topics
Proposal: Deep dive into Parsing: myst-parser, markdown-it-py and MyST Specification
Developer: @chrisjsewell
Compiling questions which I will organise into a logical interview. Please add to executablebooks/meta#672
Target Date: Mid-March 2022
February#
Attending#
Matt McKay / ANU / @mmcky
Steve Purves / Curvenote / @stevejpurves
Chris H / 2i2c / @choldgraf
Franklin Koch / Curvenote / @fwkoch
Leif Walsh / Two Sigma / @leifwalsh
Rowan Cockett / Curvenote / @rowanc1
Aakash Gupta / ANU / @aakashgc
Reports, updates, and celebrations#
sphinx-exercise==0.2.1
minor release with bug fixes and style updatessphinx-book-theme
refactor is ready for others to take a look: executablebooks/sphinx-book-themeAakash got the sphinx-theme-builder working for our theme: executablebooks/sphinx-book-theme#469
Agenda items#
[Matt] Planning to place an emphasis on Bug/Issue reduction for February (perhaps after the refactors for myst-parser, myst-nb) Issue/Bug Reduction Priorities is an issue on the meta repo to record any issues/bugs you are:
able to work on
really want fixed to move something forward
[Matt] Organise a session with Chris S on “The architecture of Jupyter Book” to flesh out some of the areas I am not familiar with such as: markdown-it / markdown-it-py etc. to make improvements for developer docs.
Can you record this?! (@mmcky – good idea)
Three Common Ways to Extend Sphinx
Overview of JupyterBook
[Steve] Thebe next steps - driven by requirements for hookup to interactive web components
refactor to a (Typescript) core, update current js library to use it.
library also made available on npm.
Issue open for discussion here executablebooks/thebe#536
@mmcky If you need beta testers, we would be happy to help test on QuantEcon projects such as: https://python-programming.quantecon.org/intro.html
[Chris H] Feedback on book theme structure / visuals?
Demo: https://sphinx-book-theme–472.org.readthedocs.build/en/472/
General agreement that this looks a lot better than the current released version.
[Chris H] Feedback on carets / toggle buttons
Demo: https://readthedocs.org/projects/sphinx-togglebutton/builds/15966583/
Chevrons instead of + signs?
Widescreen toggles - could we re-use from sphinx-design ?