# Fourth planning meeting for Scientific Python "learn" and "lectures" sites
2025-12-16

## Attendees (name)
- Dan McCloy
- Lundy Bernard
- Kirstie Whitaker

## Agenda
- review plan for learn.scientific-python.org and decide next steps

### Notes
Summary of the plan, which was converged upon last week by KW, DM, Stéfan van der Walt, and Henry Schreiner:

- the *content* for the "principles", "patterns", and "tutorials" section of the Development Guide shall move from the [`cookie` repo](https://github.com/scientific-python/cookie/tree/main/docs/pages) to the [`learn` repo](https://github.com/scientific-python/learn.scientific-python.org/tree/main/content).
- The new top-level structure of learn.scientific-python.org shall be:
- **Library Development Guide** → just the "topical guides" from existing development guide
- **Tutorials** → "tutorials" from existing development guide
- **Principles** → "principles" from existing development guide
- **Patterns** → "patterns" from existing development guide
- **Lecture Notes** → unchanged
- ~~Contributor Guide~~ → remove
- ~~Documentation Guide~~ → move to new page under "Principles"

Proposed next steps
- Switch build engine to MystMD on learn site
- also switch to build on `readthedocs`
- LB to lead; DM to do any needed translation of source formats
- copy principles, patterns, and tutorials from cookie repo to learn repo, and do necessary Myst translations at that time
- move "dev guide" up a level in content hierarchy
- add redirects
- translate dev guide to Myst (trickier; may need Henry's involvement)
- at this point, ready to receive new content

Notes from discussion:
- Going beyond the above plan, there's a need to articulate and document what the standards / criteria will be for inclusion of new material
- "by (scientific Python) maintainers, for maintainers" / "content must be useful enough to us to justify the maintenance work" seems like a good heuristic for now
- needs further thought / input, maybe at next summit
- A useful way we converged on to think about "patterns" vs "principles" vs "tutorials" is:
- tutorials are step-by-step narrative instructions for things that (almost) everyone should (or will need to) do
- patterns are short copy-pastable recipes for things that folks may or may not want/need to do for their projects (e.g., property-based testing with [hypothesis](https://hypothesis.readthedocs.io/en/latest/))
- include: "if you want/need it, this is the sensible way to do it" (the recipe is one-size-fits-most)
- principles are bigger-picture guidance than tutorials; more opinionated, less step-by-step

# Third planning meeting for Scientific Python "learn" and "lectures" sites
2025-10-21, 16:00 UTC

:::spoiler zoom link
Zoom link to join: https://washington.zoom.us/j/92404931842
:::
## Attendees (name)
:::spoiler attendees
- Dan McCloy
- Lundy Bernard
- Brian Hawthorne
- Nikolas L
- Kirstie Whitaker
- Brigitta Sipőcz
:::

## Agenda
:::spoiler agenda
- Transition of site to MystMD
- current state: MD+Jekyll+Ruby (source files in (vanilla) Markdown, site built with Jekyll)
- source files already in markdown, "just" need to convert to myST, and then:
- switch from MD+Jekyll+Ruby to myST+JupyterBookv1+Sphinx temporarily, or
- go straight to myST+`<TBD mystMD theme, JBv2?>`+MystMD engine?
- +1 vote from BS, KW, DM
- (not so complicated if we start with static build)
- complication: content is imported from https://github.com/scientific-python/cookie via GHA
- need to figure out how to host/serve (GH pages not an option)
- [name=bsipocz] why is gh pages not an option??
- should be fine for Myst engine -> static build
- question whether GH pages can serve myst content dynamically
:::
### Notes
:::spoiler notes
* Dan invited (at the Scientific Python Developer Summit in May) to lead curation of learn materials
* Desire to provide information that maintainers of core python want contributors to know - eg: interns working on project to contribute something, and skills that folks need if they are going to transition to being a maintainer
* Brian: originally thought we might need to develop some new features.... but actually looks like there's a lot of undocumented / difficult to find features!
* e.g., "cards" exist but weren't well documented
* Brigitta: pain point: myst engine doesn't let you control parallelism, so I hit memory issues (compared to JupyterBook v1) because myst tries to execute all my notebooks at the same time
* Lundy: (re: need to use CircleCI for PR deploy previews) you *can* set up PR previews from GH actions, if you set up the workflow correctly (one workflow to build + cache artifact, another to DL artifact and serve? more reading needed on exactly how it works, but internet thinks it works)
* Worth asking (Jarrod, Stéfan, Henry) about the cookie-as-submodule structure (vs cookie having its own docs, and linking/myst-incorporating those into the learn docs)
* Stéfan & Brian are, over the next ~year, working on getting MystMD engine uptake among SP projects, and that means finding and fixing the bugs / missing features

* TAKEAWAYS/AGREEMENTS:
* Lundy will take a shot at converting learn.scientific-python repo to building with Myst (statically)
* Once that PR is up and working, Dan will pitch in to convert the source files (within learn repo, not within cookie) from vanilla MD to MystMD (so we get some nice bells and whistles in the built pages)
* PR to convert cookie source files to MystMD format can come after
* changes to *content* are orthogonal and no decisions were made about that today
* Ideally we'll transition from netlify to:
* deploy and PR builds both on GH pages (first choice)
* deploy build on GH page, PR builds on CircleCI (second choice)
* deploy and PR builds on CircleCI?
* stick with Netlify? or RTD?
:::
# Second planning meeting for Scientific Python "learn" and "lectures" sites
2025-08-19, 16:00 UTC

## Attendees (name)
:::spoiler attendees
- Dan McCloy
- Jarrod Millman
- Guen Prawiroatmodjo
- Sanket Verma
- Matt Haberland
- Kirstie W
- Brigitta Sipőcz
:::

## Agenda

Anyone have additions to the agenda?

:::spoiler review of summit meeting
- [photos of whiteboard](https://discord.com/channels/786703927705862175/1371191858633506896/1372315284286738452)
- Who is in the Scientific Python community?
- core of our community is **project leads and maintainers**
- leadership of other orgs, subject matter experts, and (non-maintainer) contributors are also sometimes "in the room"
- What content should we provide?
- (contributor-oriented) content that makes our maintainer/leader roles easier
- maintenance best-practices
- onboarding materials
- (learner-oriented) materials that aren't available elsewhere
- SP lecture notes
- installer
- How should we present/package/advertise that content?
- Question not yet tackled
:::

#### current state of affairs and high-level plan
:::spoiler lectures
- content: many outdated bits
- theme: bespoke -> jupyterbook
- source: rST -> (myst) markdown
- engine: sphinx -> myst
:::
:::spoiler learn
- contributor guide (absolute beginners) -> to be moved
- can we remove without having a new home identified? it will be recoverable from git history...
- development guide -> stays
- fill in gaps? (with onboarding material)
- community guide -> fold into development guide?
- documentation guide -> fold into dev. guide? or move (where?)
:::

#### in-progress work

:::spoiler in-progress work
- lectures
- Matthew Brett & Peter Rush are working on [this](https://lisds.github.io/dsip/intro.html) complementary content to the lectures
- as far as we know nobody has stepped up to lead the Myst-ification of the lectures yet
- learn
- @drammock's proposed re-org: [learn.scientific-python.org#260](https://github.com/scientific-python/learn.scientific-python.org/issues/260) has some open questions:
- we should probably talk to leah from pyopensci about their roadmap; they're starting to add content about e.g. testing that overlaps with some of the onboarding materials proposed in #260.
- PR open for debugging in VS Code: [learn#244](https://github.com/scientific-python/learn.scientific-python.org/pull/244)
:::

---
---

# First planning meeting for Scientific Python "learn" and "lectures" sites
2025-07-15, 16:00 UTC

## Attendees (name)
:::spoiler
- Dan McCloy
- Brigitta Sipőcz
:::
## Agenda
:::spoiler
- Additions to agenda?
- review of summit meeting (drammock)
- [photos of whiteboard](https://discord.com/channels/786703927705862175/1371191858633506896/1372315284286738452)
- Who is in the Scientific Python community?
- What content should we provide?
- How should we present/package/advertise that content?
- review current state of affairs (drammock)
- lectures
- content: many outdated bits
- theme: bespoke -> jupyterbook
- source: rST -> (myst) markdown
- engine: sphinx -> myst
- learn
- contributor guide (absolute beginners) -> to be moved (where?)
- development guide -> fill in gaps
- community guide -> fold into development guide?
- documentation guide -> fold into dev. guide? or move (where?)
:::
## Commentary on the agenda
:::spoiler
### "learn"
- the name "learn" in the URL is a bit confusing
- may be perceived as too beginner-focused?
- doesn't make sense for reference material / best-practices content
- can we make a clearer distinction between the main parts of the development guide?
- topical guides are more like reference material / aimed at package maintainers
- tutorial is more pedagogical / aimed at scientists writing research code
### "lectures"
- migrating to myst engine:
- for PR reviews GHA won't work; netlify is hard to debug; circleCI?
- where is the live site hosted? Will it be able to serve the myst-based site?
- there's a chance that the outdated *content* might cause problems when serving a myst-based site (things that degraded gracefully during static site generation may not do so with myst)
- changing source to markdown: might be problematic for a sphinx build, because the source isn't in notebook format
:::