Skip to content

Refactor and update content sharing documentation #256

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+189 −210
Open

Refactor and update content sharing documentation #256

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
199 changes: 5 additions & 194 deletions community/content.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,198 +1,9 @@
# Content creation and sharing
# Share content and files

These sections describe ways that you can create content for your JupyterHub and share them with your users.

(content:nbgitpuller)=

## Distribute content with nbgitpuller

You'll often want to distribute _content_ (such as notebooks, scripts, sample
data, etc) to your users so they can do exercises, follow along with a lecture,
or use as a starting point for their own work. This content is often constantly
updated as time goes on, and needs to not overwrite your student's work if you
make an adjustment to content that has already been touched by the student.

[nbgitpuller](https://jupyterhub.github.io/nbgitpuller) is the tool
we recommend for this. The workflow goes something like this:

### Ensure that `nbgitpuller` is installed in your user environment

The default environment for 2i2c JupyterHubs has `nbgitpuller` pre-installed.
However, if you [define a custom environment for your hub's users](environment:image), you'll need to ensure that `nbgitpuller` is installed in order for users to use it!

### Put your content in a public GitHub repository

Create a repository on [GitHub](https://github.com) and start putting your
content there. This is the _source_ of the content that will be distributed
to your users. You can update it as often as you wish. While instructors will
need to know how github works, _your users will never have to interact with
git directly_.

### Generate an nbgitpuller link

Generate an [nbgitpuller link](https://jupyterhub.github.io/nbgitpuller/link). This generates a
_clickable link_ that contains within it the following pieces of information:

1. The URL to your hub. Upon clicking the link, users will be redirected to
this hub, and content will be pulled into their home directory there.
2. The URL of the git repository where the content lives.
3. The branch in the git repository where the content lives. The default
specified there is `master`, although newer GitHub repositories use `main`
as the default. You can find yours on the Github page of your content
repository
4. The default interface to open when users click this link. The default is
the classic notebook, but many other apps are available.
5. A file to open when the link is clicked. When left empty, a directory
listing with the content of the repository will be shown.

```{figure} ../images/nbgitpuller-ui.png
The [`nbgitpuller.link`](https://jupyterhub.github.io/nbgitpuller/link) user interface, along with
some important fields highlighted.
```

```{tip}
Unfortunately, RStudio does not support opening a specific file, and will
always show the home directory. Users will have to manually navigate to
the appropriate file.
```

Once you've filled these out, you can copy the link from the textbox above the form.

### Distribute your nbgitpuller link

Distribute the link you have generated to your users. Upon clicking the link,
they will be:

1. Redirected to your hub, and asked to log in if they have not already
2. The first time the link is clicked, your content repository will be pulled
into their home directory!
3. If they had already clicked the link before, any new changes in your
content repository will be pulled in. Any changes the user has made will
be [automatically
merged](https://jupyterhub.github.io/nbgitpuller/topic/automatic-merging.html)
with changes in the content repository, in such a way that the user's
changes are never overwritten. All merge conflicts will also be
automatically resolved, so users don't have to interact with git.
4. If you have picked a specific file to be displayed, the user will be
redirected to that file, open in the application you picked. If not, the
directory listing of local copy of the content repository will be shown in
the application you selected.

:::{important}

You **do not** have to create a new link each time you update your content
repository! The same link will continue to work, so you can simply ask your
users to click the link again to fetch the latest changes.

However, if you want to create links to individual files that should be
opened at specific points - like one link per class or assignment - you can
regenerate the links with different values for the file to open or interface.
As long as the hub url, content repository url and the branch name are the
same, users will be not be duplicating content.
:::

<!-- ## Serve static web content with your hub

2i2c hubs can serve static web content as a [JupyterHub service](https://jupyterhub.readthedocs.io/en/stable/reference/services.html).
This is useful for hosting documentation for your hub's community.

The content of your static site should live in a `.git` repository as a collection of static HTML files, and the website for these files will be available at a URL like:

```{toctree}
:maxdepth: 2
../sharing/documentation.md
../sharing/files.md
```
https://<hub-address>/services/docs
```

Follow these steps to set up documentation for your hub.

### Create your static HTML files

There are many ways to create your own static HTML files, and this guide doesn't cover a specific method.
Here are a few services you should try out:

- [Jupyter Book](https://jupyterbook.org/) is a tool for building rich computational narrative sites from the Jupyter community.
- [Sphinx](https://www.sphinx-doc.org/) is a popular documentation engine in Python
- [Hugo](https://gohugo.io/) is a popular static website generator that is flexible and fast.

Put the generated HTML into a `github` repository in a dedicated branch (so the branch should **only** contain the HTML files).
**Ensure that the HTML files contain relative links**, not absolute links.

:::{tip}
We highly recommend storing your source files in one branch, and automatically generating the HTML for your site via [GitHub Actions](https://docs.github.com/en/actions).
This way, your HTML files will automatically be updated when you update your site content.
:::

### Ask a 2i2c engineer to enable the documentation service for your hub

Your hub will need to be configured by a 2i2c engineer to enable the docs service (following {doc}`these instructions <infra:howto/features/static-sites>`).

- Find the **GitHub repository** and the **branch** where your HTML files are stored.
- [Send a support request](/support.md) asking them to enable this, and provide the repository/branch you found above.

Once this is deployed, your hub's documentation should be accessible at

```
https://<hub-address>/services/docs
``` -->

## Write public books that connect to a 2i2c JupyterHub

You can create public content that is designed to connect with your
2i2c JupyterHub. For example, you can create lectures from Jupyter Notebooks, and allow
students to grab their own copy of the notebook to interact with on the 2i2c
Hub.

To connect your public content with a 2i2c JupyterHub, we recommend using [Jupyter
Book](https://jupyterbook.org). This is an open-source project that allows you
to share collections of notebooks and markdown files as an online website and
book. Check out the {doc}`Jupyter Book getting started
guide<jb:start/overview>` for more information about
Jupyter Book.

You can tell Jupyter Book to place links _directly to your 2i2c JupyterHub_ on each
page that is served from a notebook. To do so, follow the [launch buttons for
JupyterHubs
instructions](https://jupyterbook.org/interactive/launchbuttons.html#jupyterhub-buttons-for-your-pages).
Make sure that you configure your `jupyterhub_url` to point to the URL of your
2i2c JupyterHub (e.g., `https://<your-hub>.2i2c.cloud`).
This will use automatically [create nbgitpuller links](content:nbgitpuller)
for you.

## Deploy documentation with Jupyter Book

2i2c can share "community documentation" alongside your hub under a special `docs.<COMMUNITY>.2i2c.cloud` subdomain. This feature can be used to establish a home for the best practice, useful resources, and rich visualisations built by your community.

:::{caution} Community Documentation is Experimental
This feature is an experimental addition by 2i2c. It may change as we learn more about how communities are using it.
:::

Using a [2i2c-authored template][2i2c-org/community-docs-template], you can quickly get started by customising an existing bare-bones Jupyter Book. This template includes examples of:

- A [landing page][guide-landing].
- Authoring content that uses [a Python Jupyter kernel][guide-kernel].
- Using rich [cross-referencing] features to create a knowledge base.

Why not start by [adding your own glossary][guide-glossary], or [adding your own logo][guide-logo]? See [](#learn-authoring) for more tips about authoring content with Jupyter Book 2 and the MyST Engine.

### Deploy your site with Jupyter Book

The current iteration of this feature requires you to deploy a Jupyter Book 2 static site from a GitHub repository using GitHub Pages. The community representative should use the [2i2c-org/community-docs-template] template to [create their own repository][use-template], and provide the 2i2c team with _temporary_ owner access. We will then ensure that various configuration such as the custom domain and GitHub Actions are set up correctly.

(learn-authoring)=

### Learn about authoring 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][jb-toolchain]. A brief overview of the MyST Markdown Syntax can be found at the [MyST Engine Typography Guide](https://mystmd.org/guide/typography).

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][guide-embed]. 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.

[MyST Markdown Guide]: https://mystmd.org/guide/quickstart
[Jupyter Book documentation]: https://next.jupyterbook.org/start
[2i2c-org/community-docs-template]: https://github.com/2i2c-org/community-docs-template
[guide-logo]: https://mystmd.org/guide/website-templates#site-options
[guide-glossary]: https://mystmd.org/guide/glossaries-and-terms
[guide-landing]: https://mystmd.org/guide/website-landing-pages
[guide-kernel]: https://mystmd.org/guide/execute-notebooks
[guide-embed]: https://mystmd.org/guide/embed#embed-from-external-myst-projects
[cross-referencing]: https://mystmd.org/guide/cross-references
[jb-toolchain]: https://next.jupyterbook.org/about/toolchain
[use-template]: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template
Binary file added images/launch-button-menu.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
9 changes: 5 additions & 4 deletions index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ They are meant for individuals who wish to learn about the service for their own
:caption: About the service
about/service/options
about/service/index
user/topics/policy/index
See a table of our running hubs! <https://infrastructure.2i2c.org/reference/hubs/>
```

Expand All @@ -32,12 +33,13 @@ Covers end-user workflows that are common for cloud-native workflows with intera

```{toctree}
:maxdepth: 2
:caption: Use the hub
:caption: Community workflows

user/topics/getting-started
user/topics/policy/index
user/topics/data/index
user/howto/index
community/content
user/howto/specify-unlisted-image
user/howto/launch-dask-gateway-cluster
```

## Administer the hub
Expand Down Expand Up @@ -68,7 +70,6 @@ Covers topics relevant to those that are leading others in a community.
:maxdepth: 2

community/events
community/content
community/strategy
```

Expand Down
2 changes: 1 addition & 1 deletion noxfile.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

build_command = ["-b", "dirhtml", ".", "_build/dirhtml"]

@nox.session(python=">=3.9")
@nox.session()
def docs(session):
session.install("-r", "requirements.txt")
if "live" in session.posargs:
Expand Down
87 changes: 87 additions & 0 deletions sharing/documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@

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

2i2c recommends communities use [Jupyter Book 2](https://next.jupyterbook.org), which uses the [MyST Document Engine](https://mystmd.org/guide), a next-generation engine for technical documentation and computational narratives. Both are developed by the [`Jupyter Book` subproject of Jupyter](https://compass.jupyterbook.org). See [the MyST Ecosystem Overview](https://mystmd.org/guide/overview) for more information about MyST and Jupyter Book.

:::{admonition} Jupyter Book integrations with 2i2c infrastructure is experimental
:class: caution
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][2i2c-org/community-docs-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][guide-landing].
- Authoring content that uses [a Python Jupyter kernel][guide-kernel].
- Using rich [cross-referencing] features to create a knowledge base.

Why not start by [adding your own glossary][guide-glossary], or [adding your own logo][guide-logo]? See [](#learn-authoring) for more tips about authoring content with Jupyter Book 2 and the MyST Engine.

(jb-deploy)=
### 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][use-template].[^gh]
- For a [custom domain next to your hub](#jb-custom-domain), 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.[^ssg] See [the MyST Engine guide to GitHub Pages](https://mystmd.org/guide/deployment-github-pages) for more documentation (it uses MyST, which behaves very similarly to Jupyter Book 2).

[^gh]: You can use a different book structure rather than the template if you like. In this case, just make sure you're hosting the book's source files on GitHub in order to use GitHub pages!

[^ssg]: In this case, we use Jupyter Book / MyST as a [Static Site Generator](https://en.wikipedia.org/wiki/Static_site_generator), which creates static HTML files.

(jb-custom-domain)=
## 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](#jb-deploy), 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](#jb-deploy).
- 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:

1. Configure your book to add launch buttons by following the [mystmd instructions launch buttons](https://mystmd.org/guide/website-launch-buttons).
2. 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](https://compass.2i2c.org/projects/managed-hubs/showcase-hub/):

```{figure} ../images/launch-button-menu.png
:width: 75%
The launch button pop-up with the 2i2c showcase hub URL pasted. Clicking the {kbd}`Launch` button will ask your user to log-in, and then launch an interactive Jupyter server with the source file of the current page loaded for editing.
```

(learn-authoring)=

## 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][jb-toolchain]. A brief overview of the MyST Markdown Syntax can be found at the [MyST Engine Typography Guide](https://mystmd.org/guide/typography).

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][guide-embed]. 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.

[MyST Markdown Guide]: https://mystmd.org/guide/quickstart
[Jupyter Book documentation]: https://next.jupyterbook.org/start
[2i2c-org/community-docs-template]: https://github.com/2i2c-org/community-docs-template
[guide-logo]: https://mystmd.org/guide/website-templates#site-options
[guide-glossary]: https://mystmd.org/guide/glossaries-and-terms
[guide-landing]: https://mystmd.org/guide/website-landing-pages
[guide-kernel]: https://mystmd.org/guide/execute-notebooks
[guide-embed]: https://mystmd.org/guide/embed#embed-from-external-myst-projects
[cross-referencing]: https://mystmd.org/guide/cross-references
[jb-toolchain]: https://next.jupyterbook.org/about/toolchain
[use-template]: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template
Loading