[Platform Initiative] Jupyter Book MVP for 2i2c communities

[Gman0909]

Description

We wish to build a MyST MVP that will allow communities to build interactive starter documentation to help them bootstrap themselves and provide their users with a rich, interactive and informative onboarding experience. The MVP will, at minimum, allow for the creation of landing pages, and the hosting of content such as Code of Conduct pages, content and image galleries and and interactive tutorials, complete with responsive hero blocks and wide screen support.

User stories for this initiative

Here's a proposal for user stories that should be possible on our hubs as part of this MVP.

• As a community admin, I want to automatically get a Jupyter Book site with my hub (e.g., at docs.myhub.2i2c.cloud).
  • I do not want to have to manually connect it to my hub(s) for launch functionality.
  • If an automated solution is not feasible, I want to be able to copy a template and hook it up to my hub with minimal manual steps.
  • If I have a different technical preference for my community knowledge base, I want the ability to disable this workflow.
  • Relevant Productboard feature
• I want this skeleton of this book to follow best-practices as defined by 2i2c, and have at least three sections in the skeleton :
  • A landing page to orient readers to the community: e.g., a brochure-style page, such as https://www.pangeo.io/.
    • This needs to support a wide "welcome" message, a description of what the community is and what it does, and two buttons to "learn more" in the documentation and "go to the hub" for community members.
    • This page should be a myst content page like all other docs pages.
  • A knowledge base to learn community workflows. e.g., community how to guides and tutorials, such as the CryoCloud tutorials and How-Tos.
    • I want a sample piece of content for each one already there.
  • A showcase to share and discover user content: A place for community members to upload content for sharing with others in my community (e.g., the pangeo gallery)
    • It should automatically display a list of all source files in a folder / yaml file / etc sorted with key community metadata.
    • It should be displayable as a gallery with embedded images and the results of computations used as an image.
  • (🙏 only for MVP if it's not a ton of work): A blog to publish ongoing communication for internal and external consumption (e.g., the Pangeo blog).
    • The blog should have an RSS feed.
    • It should otherwise behave the same as any other content on the docs.
• As a content author, I want to be able to update content on the book by pushing markdown files and editing a myst.yml file in a github repository, and have it automatically update on the website.
  • (🙏 only for MVP if it's not a ton of work) I want to push/pull content from my community's knowledge repository within JupyterHub (either JupyterLab or VSCode) in less than 3 clicks and no command line usage.
  • (➡️ for the future): I want to be able to publish content to CurveNote just as easily in order to have a public record that is more discoverable/archivable/etc for publishing workflows. (Relevant Productboard feature)
• As a community member reading community docs, I want to be able to launch into my community's JupyterHub straight from my book (Relevant Productboard feature).
  • Should support at least one of my community's JupyterHub and BinderHub directly.
  • The source file of the current page should be opened in my interactive session.
  • (🙏 only for MVP if it's not a ton of work) I want to be able to connect a Thebe session to my community's content with computation provided by my BinderHub.
  • (➡️ for the future): I want to be able to launch arbitrary Jupyter Book content with my JupyterHub / BinderHub. (Relevant Productboard feature)
• As a content author, I want to be able to share content to non-community-members that runs on my community's BinderHub.
  • (only for MVP if it's not a ton of work) As a community admin, I want to be able to control and see what content can run on my community's BinderHub so that I know it isn't being used for abuse or unsustainable usecases.

Definition of Done

• Each of the user stories above is enabled, or explicitly pushed to a future initiative.
• All new functionality is fully documented.
• A fully working implementation is validated by at least one of our communities.
• We've defined the mechanisms that trigger when and how this is deployed for new communities (e.g. only in certain tiers, automatically for everyone, etc).
• The new functionality is communicated to our communities.

Driving use-cases

These are use-cases that we'll use to drive forward development, prototyping, and validation of this initiative:

• [P&S Initiative] AGU2024 Demos demo-gallery#2

To do

• Validate list of user stories above with communities via mockup/prototype
• Create a prototype using the new features based on ClimateRisk use case (see [P&S Initiative] AGU2024 Demos demo-gallery#2).
• Demonstrate the prototype to target communities and gather feedback
• Create starter documentation for the new features.
• Generalize and automate the prototype so it can be deployed for new communities with minimal toil.
• Communicate the new features to our communities

[Gman0909]

@agoose77 First draft in.

[choldgraf]

I've gone through and updated the issue body to incorporate the user stories that I think should satisfy this MVP. They focus around a basic knowledge base workflow for communities, and providing them the basic building blocks they'd need to start using a Jupyter Book for their hub.

Consider this a proposal for feedback and editing from @agoose77, @Gman0909 , @jmunroe , and @colliand . I think that this initiative is likely relevant to all of your current priorities so don't hesitate to suggest if you think there is something critically missing here.

[Gman0909]

I've taken the liberty of editing the body of the original issue to add relevant PB links, and have added one feature to PB to capture one of the new use cases.

[colliand]

I like the way the body describes the MyST MVP. Thanks to all for shaping this!

While reading through the text above, I was thinking often of the binder services we are exploring in the "Public Tier" and the "Member Tier". The BYOB line related to Thebe is especially relevant here so can perhaps be left for future refinement. That said, there is one user story that I think needs to be captured into a near-term product delivery target:

As a content author, I want to be able to generate "magic links" that allow me to share interactive content with readers using 2i2c's public binder and my member university's bigger binder.

Should this feature for "easy power to disseminate interactive content" be integrated with the MyST initiative or be refined elsewhere?

[choldgraf]

@colliand to me the user story you show above is captured by the last one on the list (though it is more generalized than yours):

As a content author, I want to be able to share content to non-community-members that runs on my community's BinderHub.

Do you agree we can just refine the one above to incorporate a key functionality you think it's missing? Jim agrees

One quick note: I feel like "generate magic links" and "publish to a Jupyter Book w/ a launch button" are two related but distinct stories...I'm curious which of the two feels more important to prioritize. Perhaps @jmunroe can suggest which would be most useful for the AGU demos

Jim: Examples that showcase how 2i2c enables nearly immediate transportation of a reader to the knowledge frontier are crucial assets for sales enablement. I consider a flat list of "magic links" to these kinds of showcases a higher priority than JupyterBook with launchers at this time. That said, a MyST gallery of showcases that can be launched into interactive binder sessions would be fantastic.