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, @chrisjsewell

    • over 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 spec

    • unified-myst, the new unified ecosystem implementation, will also be “spec compliant”!

    • python side hasn’t been adressed quite yet.

  • Unified MyST

    • 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”

  • 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)

    • executablebooks/meta#672

    • 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#

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 to myst-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)#

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#

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:

    1. able to work on

    2. 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

  • [Chris H] Feedback on book theme structure / visuals?

  • [Chris H] Feedback on carets / toggle buttons