Community documentation with Jupyter Book

Community documentation with Jupyter Book#

Community documentation is a great way to spread learning and knowledge across your user base. You can share workflows, tutorials, examples meant for re-use, and topics to help others understand the key ideas in your community.

Where to find examples of community books

Check out Project Pythia and the CryoCloud for real-world examples of community books.

2i2c recommends communities use Jupyter Book 2, which uses the MyST Document Engine, a next-generation engine for technical documentation and computational narratives. Both are developed by the Jupyter Book subproject of Jupyter. See the MyST Ecosystem Overview for more information about MyST and Jupyter Book.

Jupyter Book integrations with 2i2c infrastructure is experimental

This feature is an experimental addition by 2i2c. It may change as we learn more about how communities are using it.

Get started with Jupyter Book#

Using the 2i2c community documentation template, you can get started by customising an existing bare-bones Jupyter Book. This template includes examples of:

Basic configuration for a Jupyter Book.
A landing page.
Authoring content that uses a Python Jupyter kernel.
Using rich cross-referencing features to create a knowledge base.

Why not start by adding your own glossary, or adding your own logo? See Learn how to author content with Jupyter Book and MyST Markdown for more tips about authoring content with Jupyter Book 2 and the MyST Engine.

Deploy your Jupyter Book as a website#

To deploy a Jupyter Book online, we recommend the following steps:

The Community Representative should use the 2i2c-org/community-docs-template template to create their own repository.[1]
For a custom domain next to your hub, provide the 2i2c team with temporary owner access to the repository. We will ensure that various configuration such as the custom domain and GitHub Actions are set up correctly.
Use GitHub Pages to host your book content online.[2] See the MyST Engine guide to GitHub Pages for more documentation (it uses MyST, which behaves very similarly to Jupyter Book 2).

Get a dedicated docs URL next to your hub#

Once your documentation is deployed online, 2i2c can give your community a special URL that makes your documentation more memorable and easier to find. If your hub is located at <COMMUNITY>.2i2c.cloud, then your documentation will be hosted at the subdomain:

docs.<COMMUNITY>.2i2c.cloud

To enable this, first get your Jupyter Book hosted online, then open a support ticket with the 2i2c team requesting that this be done.

Add buttons that launch interactive sessions on your hub#

You can create content that is designed to connect with your 2i2c JupyterHub. For example, you can:

Create course lectures using Jupyter Notebooks as the source files.
Host your book online by following the instructions above.
Create a button on each page that will let students launch an interactive session on their hub, with their own copy of the content ready for editing.

To do so, follow these steps:

Configure your book to add launch buttons by following the mystmd instructions launch buttons.
Instruct your users to paste in the URL of your community hub to the launch button pop-up (e.g., https://<your-hub>.2i2c.cloud).

For example, here’s what it would look like to use the URL of the 2i2c showcase hub:

Learn how to author content with Jupyter Book and MyST Markdown#

The Jupyter Book documentation and the MyST Markdown Guide are useful resources for learning about Jupyter Book 2 and the MyST Engine that powers it. To understand how Jupyter Book 2 and the MyST engine relate to one another, see this documentation page. A brief overview of the MyST Markdown Syntax can be found at the MyST Engine Typography Guide.

The MyST Engine implements powerful sharing and reusing features. One of the most exciting of these is the ability to preview and embed content from external MyST sites. This can be used to richly reference and include figures, glossary terms, and even entire documents from useful resources! Amongst communities that share a set of best practices and understanding, this feature may be particular useful for building upon the work of others.