Milestone: Jupyter Book announcement at SciPy 2025

[choldgraf]

In our last JB meeting we agreed to use SciPy 2025 as a milestone for signal-boosting Jupyter Book. SciPy 2025 is July 7th, 2025. That gives us about 3 months to get major functionality ready by then. This issue is for tracking this overall effort. It will give our high-level goal and principles to follow, and we will use the Jupyter Book priorities board to track specific issues.

Where is the roadmap for this initiative?

The For SciPy 2025 Announcement column in the Jupyter Book priorities board. Assume that any card in that column is a blocker before we feel comfortable making a larger public announcement about Jupyter Book at SciPy.

User workflow to focus on

Given the closeness between Scientific Python and the SciPy community, let's use the Scientific Python tracking issue to help us prioritize. I think that this will both help us accomplish a few goals:

1. Meet the needs of the attendees at the conference, because they're similar to the SP community.
2. Set the SP project up so that it's comfortable endorsing MyST as its engine, in case it wants to use SciPy to signal-boost its own efforts like this
3. Encourage upstream contirbutors, since SP has more developers than many communities this may be a better opportunity to grow the team

If @stefanv is willing, I'd love to offer him the authority to act as a "canary" here and either signal-boost issues for prioritization, or define a "definition of enough" for this milestone.

Principles to follow

SciPy is an audience we've been connected with for a long time, so it may have more experience with Jupyter Book 1 than average audiences. It's a more technically confident group that is willing to deal with paper cuts as long as they have a way to get around major issues. To this extent, here are the principles to follow:

There should be no major surprises switching from Jupyter Book 1. Some missing or different functionality is OK, but any major features that expect most JB1 users to be using should be present. So for example, major HTML theme functionality should largely be the same, while replicating custom Sphinx extension functionality is not a "major feature" because only a subset of JB1 users write their own extensions.

We should focus on HTML outputs. The SciPy community tends to be more interested in modern and innovating communicating and writing workflows, rather than traditional publishing workflows. If we must choose, we should prioritize having an excellent static HTML-based experience.

We should ensure that the project has enough guidance for new users to self-teach, and then to contribute. If there's an influx of new users with a technical background, we should ensure that they have all the documentation in place for them to understand the project as a whole, navigate its tooling, and use each core tool effectively. We should also make sure there are better pathways for learning the codebase and opportunities to connect and contribute.

Definition of done

This issue will be complete when we've got an empty "for scipy 2025" column in the JB priorities board

[choldgraf]

I invite others to take a look at the rationale above, and the issues in the column we're using to track this work, and suggest additions/removals to either what's there, or re-prioritization (top of the column are things to focus on next).

[stefanv]

Hi @choldgraf and others; I am excited to see what we can do to get JB2 ready for the SciPy announcement.

I can think of at least three target groups of users (who am I missing?):

1. Existing authors of books who want to port
2. Users who want to write a book, starting afresh
3. Website authors (academic profile pages, course websites, etc.)

(4. Those who want to write papers; putting this in brackets, because although I think SciPy2025 would be a great time to advertise to these users, there's perhaps not much to be done in preparation.)

If we care about group (1), it would be good to find some existing books written using JB1 and try to port them (I can help, if you point me to them).

For group 2, we need to ensure the docs are in good shape (happy to help with that too, I see it's already an issue).

For group 3, well, we have a fair amount of work to do, but this is work that we need for Scientific Python as well (blogs, custom CSS themes, footers, social media icons, download widget, documentation rendering, etc.), and that I'm planning on working on anyway.

[choldgraf]

I've removed a couple of the more complex issues from our scipy target (specifically the one about "lists of pages" because that one might be fairly complex as @fperez pointed out). We have a couple of theme-related issues remaining in there, as well as the (more complex) output parsing issue that is already in progress.

I'm trying to shrink this down to some minimal quality-of-life things and features that communities would expect to have. I welcome others to recommend more things we could remove from the "scipy" column so that we don't overload ourselves. I'd rather be too conservative than too ambitious given what little capacity we have.

Personally, I am going to focus most of my time on the documentation side, especially for contributor documentation so that we can make it easier for others to contribute and join the team.

[rowanc1]

Just a quick note on this, we will have a talk on the project. Looks like it is on Thursday afternoon of the conference.

[bsipocz]

This has happened, closing the issue.