# 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. - github: https://github.com/executablebooks/myst-spec - dist: https://unpkg.com/browse/myst-spec/dist/ - 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`](https://github.com/executablebooks/unified-myst), the new unified ecosystem implementation, will also be "spec compliant"! - python side hasn't been adressed quite yet. - [Unified MyST](https://github.com/executablebooks/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](https://github.com/micromark/micromark) (and that is bundled in [remark](https://remarkjs.com/)) - The [unified-myst](https://github.com/executablebooks/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! - https://transform.softwareunderground.org/ - 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)](https://ebp-sphinx-exercise.readthedocs.io/en/latest/syntax.html#alternative-gated-syntax). 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) - https://github.com/executablebooks/meta/issues/672#issue-1147568262 - 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! - https://github.com/executablebooks/mystjs - https://executablebooks.github.io/mystjs - 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 https://github.com/executablebooks/MyST-NB/pull/380 - soon-to-be-released sphinx-book-theme (v0.3). in pre-release now but haven't gotten any negative feedback. https://github.com/executablebooks/sphinx-book-theme/releases/tag/v0.3.0rc1 - sphinx-togglebutton also released w/ smaller footprint: https://github.com/executablebooks/sphinx-togglebutton/releases/tag/v0.3.0 ### 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) - https://github.com/executablebooks/meta/issues/681 - https://github.com/executablebooks/MyST-NB/pull/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 https://github.com/executablebooks/meta/issues/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 updates - `sphinx-book-theme` refactor is ready for others to take a look: https://github.com/executablebooks/sphinx-book-theme - Aakash got the sphinx-theme-builder working for our theme: https://github.com/executablebooks/sphinx-book-theme/pull/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](https://github.com/executablebooks/meta/issues/649) is an issue on the meta repo to record any issues/bugs you are: 1. able to work on 1. 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 https://github.com/executablebooks/thebe/issues/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 ?