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

Epics in this initiative

Build MyST Theme for community documentation

To provide our communities with high quality documentation that can sit alongside their Hubs, we need to develop a few components for myst-theme that open up new workflows like landing pages.

In order to ship these features to deployed sites, we'll need to start with a custom theme (likely a remix of the book-theme) that includes the new components. Over time, we may be able to upstream these along with the theme itself.

Relevant Productboard feature

Tasks

Preview Give feedback

1. Plan the design for a MyST theme with a landing page #5339
   0 of 4
   +0
   
2. Build a structured gallery MyST component #5341
   +0
3. Add support for buttons in MyST #5346
   +0
   
4. Deploy custom theme for Jupyter Book 2 home-page

Document process for deploying Jupyter Book alongside a hub

In this initiative we define need to deploy a Jupyter Book site alongside a Hub, e.g. docs.myhub.2i2c.cloud.

There are many different ways to do this, that involve the following questions:

• What kind of book deployment?
  • live server e.g. CurveNote, 2i2c
  • static file server e.g. GitHub Pages, AWS S3, ReadTheDocs
• Where to host the source artifacts (MD files, etc)? e.g. GitHub
• Where to perform compute during site building.

In turn, these questions depend upon the desired workflow for authoring, collaboration, and deployment. Whilst there are advantages to running a custom server (namely performance and complexity surface), the MVP for this should probably use a familiar workflow (see below).

Tasks

Preview Give feedback

1. Update Infrastructure documentation to reflect new community-site deployment #5335
   +0
2. Update Service Guide documentation to reflect new community-site feature #5338
   +0

Create a skeleton template repository for deploying community documentation

To serve this initiative, we should create a GitHub template repository that can be used to bootstrap a community documentation site. This will require #5342.

This template must contain the following items:

Tasks

Preview Give feedback

1. CI/CD for deploying a Jupyter Book site to GitHub Pages via HTML export, with no BASE_URL
2. A skeleton landing page
3. A skeleton knowledge base
4. A skeleton showcase

Improve the Jupyter Book 2 Launch Button UX

At the time of the MyST retreat co-located with AGU, there was a discussion around the benefits of collapsing the two-tab "hub" and "binder" UI for bring-your-own-binder/hub (BYOB) into a single URL and launch button. Theoretically, we should be able to detect what kind of deployment the user is trying to make according to the URL. Simplifying this will reduce the amount of UI we need to show the user, and make it possible start talking at a higher-level with respect to the "launch" feature.

We also want to support pre-defining a set of BinderHub / JupyterHub targets that community readers can jump into. These are normally resources that are associated with the deployment e.g. https://docs.<COMMUNITY>.2i2c.cloud/. We should extend the theme component to facilitate this.

Making this enhancement will require some changes in jupyter-book/myst-theme, jupyterhub, etc.

Tasks

Preview Give feedback

1. Allow programmatic identification of JupyterHub and BinderHub #5347
   2 of 2
   +0
   
2. Add "awesomebar"-like UX to MyST launch button #5348
   +0
   
3. Update MyST launch button UI to inform users of constraints #5349
   +0
4. Add support for pre-populated BinderHub/JupyterHub to MyST launch button #5350
   +0

---

**Original 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.

[agoose77]

Something that one of the linked PB features mentions is @colliand's concept of a user-identity that transcends a single hub: https://2i2c.productboard.com/feature-board/7803674-product-ideas/features/29842699/detail

In my understanding, this is orthogonal to a feature that associates a JupyterHub / BinderHub instance with a set of community documentation (e.g. https://docs.community.2i2c.cloud/).

For the purpose of this MVP initiative, I think my feeling is that the user-identity component is a future-feature. Does that match the other stakeholder's impressions?

[Gman0909]

For the purpose of this MVP initiative, I think my feeling is that the user-identity component is a future-feature. Does that match the other stakeholder's impressions?

Yes, I feel this is beyond the scope of an MVP.