Sub-issues
#5335 - Update Infrastructure documentation to reflect new community-site deployment
#5338 - Update Service Guide documentation to reflect new community-site feature
#5347 - Allow programmatic identification of JupyterHub and BinderHub
#5348 - Add “awesomebar”-like UX to MyST launch button
#5349 - Update MyST launch button UI to inform users of constraints
#5511 - Follow up on awesomebar PR #5348 [myst]
#5346 - Add support for buttons in MyST
#5339 - Plan the design for a MyST theme with a landing page
#5482 - Build book-theme variant with landing page support
#5549 - Follow up on landing pages PRs #5482 [myst]
#5557 - Refine “skeleton template repository” for #5045
#5676 - Engage with Project Pythia on improvements for MyST landing pages
#5829 - Deploy a basic template for community documentation with a landing page and knowledge base
#5904 - Review Infrastructure Guide PR for MyST MVP
#5911 - Improve layout of
justifiedlanding-page blocks
Participate in the issue: github
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 where they fit with the general vision of the project.
Tasks¶
#5339
#5346
#5482
#5549
#5676
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:
Refine the work required to deploy a static GitHub pages site alongside a Jupyter Hub
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¶
#5335
#5338
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 2i2c
This template must contain the following items:
Tasks¶
#5829
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¶
#5347
#5348
#5349
#5511
**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.
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:
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 2i2c
-org /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
Status: Done
Back to: All Initiatives