Skip to content
Snippets Groups Projects
Unverified Commit ac6ffcf7 authored by Ryan C Cooper's avatar Ryan C Cooper Committed by GitHub
Browse files

:books: DOCS: update instructions for using w/ jupyterhub and binder (#1097)

parent 8db38bee
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/interactive/launchbuttons.ipynb
+ 38
− 14
View file @ ac6ffcf7
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
# Launch buttons for interactivity # Launch buttons for interactivity
Because Jupyter Books are built with Jupyter notebooks, you can allow users to launch Because Jupyter Books are built with Jupyter notebooks, you can allow users to launch
live Jupyter sessions in the cloud directly from your book. This lets readers quickly interact with your content in a traditional coding interface. live Jupyter sessions in the cloud directly from your book. This lets readers quickly interact with your content in a traditional coding interface.
There now exist numerous online notebook services - a good comparison is provided [in this article](https://www.dataschool.io/cloud-services-for-jupyter-notebook) - and the following sections describes the available integrations provided by Jupyter Book. There now exist numerous online notebook services - a good comparison is provided [in this article](https://www.dataschool.io/cloud-services-for-jupyter-notebook) - and the following sections describes the available integrations provided by Jupyter Book.
In each case, you'll need to tell Jupyter Book where your book content lives online. In each case, you'll need to tell Jupyter Book where your book content lives online.
To do so, use this configuration in `_config.yml`: To do so, use this configuration in `_config.yml`:
```yaml ```yaml
# Information about where the book exists on the web # Information about where the book exists on the web
repository: repository:
url : https://github.com/yourusername/yourbookrepo # Online location of your book url : https://github.com/yourusername/yourbookrepo # Online location of your book
path_to_book : path/to/book # Optional path to your book, relative to the repository root path_to_book : path/to/book # Optional path to your book, relative to the repository root
branch : master # Which branch of the repository should be used when creating links (optional) branch : master # Which branch of the repository should be used when creating links (optional)
``` ```
The `repository:` configuration line uses `url`, `path_to_book`, and `branch` to find your notebook
files.
- The `url` should be a GitHub repository that includes your source files used to build the
Jupyter Book. Your repository should include:
- `_config.yml`
- `_toc.yml`
- `requirements.txt`: packages for binder or general reproducibility
- _the source files in *.ipynb and *.md_
- The `path_to_book` should used if your book is in a sub-folder of your repository (e.g. `docs/` or
`book/`)
- The `branch` should be the branch where your book's source files are stored. It _should not be_
the [`gh-pages` branch](https://jupyterbook.org/publish/gh-pages.html).
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
## The notebook interface ## The notebook interface
Binder and JupyterHub sessions can be opened using either the "classic" Jupyter Notebook or the new JupyterLab interface backend (see [jupyter.org](https://jupyter.org) for more details). Binder and JupyterHub sessions can be opened using either the "classic" Jupyter Notebook or the new JupyterLab interface backend (see [jupyter.org](https://jupyter.org) for more details).
This is configured using: This is configured using:
```yaml ```yaml
launch_buttons: launch_buttons:
notebook_interface: "jupyterlab" # or "classic" notebook_interface: "jupyterlab" # or "classic"
``` ```
One thing to take into account when choosing the interface is that notebooks written in the [MyST Markdown](../file-types/myst-notebooks.md) text-based format will not be opened as notebooks out-of-the-box. One thing to take into account when choosing the interface is that notebooks written in the [MyST Markdown](../file-types/myst-notebooks.md) text-based format will not be opened as notebooks out-of-the-box.
If you wish for these files to be opened as notebooks then firstly you must ensure that [`jupytext>=0.16`](https://jupytext.readthedocs.io/en/latest/formats.html#myst-markdown) is installed in the Binder/JupyterHub environment for your book (no support for this feature exists in Google Colab). You then have two options: If you wish for these files to be opened as notebooks then firstly you must ensure that [`jupytext>=0.16`](https://jupytext.readthedocs.io/en/latest/formats.html#myst-markdown) is installed in the Binder/JupyterHub environment for your book (no support for this feature exists in Google Colab).
You then have two options:
- Use the "classic" interface, which will then immediately open these files as notebooks. - Use the "classic" interface, which will then immediately open these files as notebooks.
- The "jupyterlab" interface (at the time of writing) has not yet implemented this behaviour, and so you will need to instruct readers to right-click the Markdown file and click "Open in notebook editor". - The "jupyterlab" interface (at the time of writing) has not yet implemented this behaviour, and so you will need to instruct readers to right-click the Markdown file and click "Open in notebook editor".
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
## {term}`Binder` buttons for your pages ## {term}`Binder` buttons for your pages
{term}`BinderHub` can be used to build the environment needed to run a repository, and provides {term}`BinderHub` can be used to build the environment needed to run a repository, and provides
a link that lets others interact with that repository. If your Jupyter Book is hosted online a link that lets others interact with that repository. If your Jupyter Book is hosted online
on GitHub, you can automatically insert buttons that link to the Jupyter Notebook running in a BinderHub. on GitHub, you can automatically insert buttons that link to the Jupyter Notebook running in a BinderHub.
When a user clicks the button, they'll be taken to a live version of the page. If your code When a user clicks the button, they'll be taken to a live version of the page. If your code
doesn't require a significant amount of CPU or RAM, you can use the free, public BinderHub running doesn't require a significant amount of CPU or RAM, you can use the free, public BinderHub running
at https://mybinder.org. at https://mybinder.org.
To automatically include Binder link buttons in each page of your Jupyter Book, use the following To automatically include Binder link buttons in each page of your Jupyter Book, use the following
configuration in `_config.yml`: configuration in `_config.yml`:
```yaml ```yaml
launch_buttons: launch_buttons:
binderhub_url: "https://mybinder.org" # The URL for your BinderHub (e.g., https://mybinder.org) binderhub_url: "https://mybinder.org" # The URL for your BinderHub (e.g., https://mybinder.org)
``` ```
By adding this configuration, along with the repository url configuration above, Jupyter Book By adding this configuration, along with the repository url configuration above, Jupyter Book
will insert Binder links to any pages that were built from notebook content. will insert Binder links to any pages that were built from notebook content.
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
## JupyterHub buttons for your pages ## JupyterHub buttons for your pages
JupyterHub lets you host an online service that gives users their own Jupyter servers JupyterHub lets you host an online service that gives users their own Jupyter servers with an environment that you specify for them.
with an environment that you specify for them. It allows you to give users access to It allows you to give users access to resources and hardware that you provision in the cloud, and allows you to authenticate users in order to control who has access to your hardware.
resources and hardware that you provision in the cloud, and allows you to authenticate users
in order to control who has access to your hardware.
Similar to Binder link buttons, you can also automatically include interact links that send
your readers to a JupyterHub that is running a live, interactive version of your page. This
is accomplished using the [nbgitpuller](https://github.com/jupyterhub/nbgitpuller) server
extension.
You can configure the location of the JupyterHub (which you may set up on your own using a guide Similar to Binder link buttons, you can also automatically include interact links that send your readers to a JupyterHub that is running a live, interactive version of your page.
such as [zero to jupyterhub for kubernetes](https://z2jh.jupyter.org) or [the littlest jupyterhub](https://tljh.jupyter.org)) with the following configuration: This is accomplished using the [nbgitpuller](https://github.com/jupyterhub/nbgitpuller) server extension.
You can configure the location of the JupyterHub (which you may set up on your own using a guide such as [zero to jupyterhub for kubernetes](https://z2jh.jupyter.org) or [the littlest jupyterhub](https://tljh.jupyter.org)) with the following configuration:
```yaml ```yaml
launch_buttons: launch_buttons:
jupyterhub_url: "your-hub-url" # The URL for your JupyterHub. (e.g., https://datahub.berkeley.edu) jupyterhub_url: "your-hub-url" # The URL for your JupyterHub. (e.g., https://datahub.berkeley.edu)
``` ```
On your JupyterHub server, you need two dependencies installed:
1. To clone the notebook with the launch link, the server needs
[`nbgitpuller`](https://jupyterhub.github.io/nbgitpuller/).
2. To open myst-markdown as notebooks, the server needs
[`jupytext>=0.16`](https://jupytext.readthedocs.io/en/latest/formats.html#myst-markdown).
You can add the following line to your `DockerFile`:
```
RUN pip install jupytext nbgitpuller
```
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
## {term}`Google Colab` buttons for your pages ## {term}`Google Colab` buttons for your pages
If your Jupyter Book is hosted online on GitHub, you can automatically insert buttons that link to the Jupyter Notebook running on [Google Colab](https://colab.research.google.com/). When a user clicks the button, they'll be taken to a live version of the page. If your Jupyter Book is hosted online on GitHub, you can automatically insert buttons that link to the Jupyter Notebook running on [Google Colab](https://colab.research.google.com/).
When a user clicks the button, they'll be taken to a live version of the page.
Similar to Binder link buttons, you can automatically include Google Colab link buttons with the following configuration in `_config.yml`: Similar to Binder link buttons, you can automatically include Google Colab link buttons with the following configuration in `_config.yml`:
```yaml ```yaml
launch_buttons: launch_buttons:
colab_url: "https://colab.research.google.com" colab_url: "https://colab.research.google.com"
``` ```
```{note} ```{note}
Google Colab links will only work for pages that have the `.ipynb` extension. Google Colab links will only work for pages that have the `.ipynb` extension.
``` ```
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
(launch/thebelab)= (launch/thebelab)=
## Live interactive pages with ThebeLab ## Live interactive pages with ThebeLab
This section describes how to bring interactivity to your book. This lets users This section describes how to bring interactivity to your book. This lets users
run code and see outputs *without leaving the page*. Interactivity is provided run code and see outputs *without leaving the page*. Interactivity is provided
by a kernel running on the public [**MyBinder**](https://mybinder.org) service. by a kernel running on the public [**MyBinder**](https://mybinder.org) service.
```{warning} ```{warning}
This is an experimental feature, and may change in the future or work unexpectedly. This is an experimental feature, and may change in the future or work unexpectedly.
``` ```
To make your content interactive without requiring readers to leave the current page, To make your content interactive without requiring readers to leave the current page,
you can use a project called [Thebe](https://github.com/minrk/thebelab). you can use a project called [Thebe](https://github.com/minrk/thebelab).
This provides you with a button that, when clicked, will convert each code cell into This provides you with a button that, when clicked, will convert each code cell into
an **interactive** cell that can be edited. It also adds a "run" button to each cell, an **interactive** cell that can be edited. It also adds a "run" button to each cell,
and connects to a Binder kernel running in the cloud. and connects to a Binder kernel running in the cloud.
As an alternative to pressing the Thebe button at the top of the page, you As an alternative to pressing the Thebe button at the top of the page, you
can press the <img src="../images/logo/edit-button.svg" alt="" style="width: 20px; display: inline;" /> symbol in the top right corner of each code cell to start the can press the <img src="../images/logo/edit-button.svg" alt="" style="width: 20px; display: inline;" /> symbol in the top right corner of each code cell to start the
interactive mode. interactive mode.
To add a Thebe button to your Jupyter Book pages, use the following configuration: To add a Thebe button to your Jupyter Book pages, use the following configuration:
```yaml ```yaml
launch_buttons: launch_buttons:
thebe : true thebe : true
``` ```
In addition, you can configure the Binder settings that are used to provide a kernel for In addition, you can configure the Binder settings that are used to provide a kernel for
Thebe to run the code. These use the same configuration fields as the BinderHub interact Thebe to run the code. These use the same configuration fields as the BinderHub interact
buttons described above. buttons described above.
For an example, click the **Thebe** button above on this page, and run the code below. For an example, click the **Thebe** button above on this page, and run the code below.
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
import numpy as np import numpy as np
import matplotlib.pyplot as plt import matplotlib.pyplot as plt
plt.ion() plt.ion()
x = np.arange(500) x = np.arange(500)
y = np.random.randn(500) y = np.random.randn(500)
fig, ax = plt.subplots() fig, ax = plt.subplots()
ax.scatter(x, y, c=y, s=x) ax.scatter(x, y, c=y, s=x)
``` ```
%% Cell type:markdown id: tags: %% Cell type:markdown id: tags:
### Running cells in Thebe when it is initialized ### Running cells in Thebe when it is initialized
Sometimes you'd like to initialize the kernel that Thebe uses by running Sometimes you'd like to initialize the kernel that Thebe uses by running
some code ahead of time. This might be code that you then hide from the user some code ahead of time. This might be code that you then hide from the user
in order to narrow the focus of what they interact with. This is possible in order to narrow the focus of what they interact with. This is possible
by using Jupyter Notebook tags. by using Jupyter Notebook tags.
Adding the tag `thebe-init` to any code cell will cause Thebe to Adding the tag `thebe-init` to any code cell will cause Thebe to
run this cell after it has received a kernel. Any subsequent Thebe cells run this cell after it has received a kernel. Any subsequent Thebe cells
will have access to the same environment (e.g. any module imports made in the will have access to the same environment (e.g. any module imports made in the
initialization cell). initialization cell).
You can then pair this with something like `hide-input` in order to run You can then pair this with something like `hide-input` in order to run
initialization code that your user doesn't immediately see. For example, initialization code that your user doesn't immediately see. For example,
below we'll initialize a variable in a hidden cell, and then tell another below we'll initialize a variable in a hidden cell, and then tell another
cell to print the output of that variable. cell to print the output of that variable.
%% Cell type:code id: tags:hide-input,thebe-init %% Cell type:code id: tags:hide-input,thebe-init
``` python ``` python
my_hidden_variable = 'wow, it worked!' my_hidden_variable = 'wow, it worked!'
``` ```
%% Cell type:code id: tags: %% Cell type:code id: tags:
``` python ``` python
# The variable for this is defined in the cell above! # The variable for this is defined in the cell above!
print(my_hidden_variable) print(my_hidden_variable)
``` ```
......
docs/start/publish.md
+ 17
− 0
View file @ ac6ffcf7
...@@ -5,6 +5,23 @@ The best way to do this is with a service that hosts **static websites** ...@@ -5,6 +5,23 @@ The best way to do this is with a service that hosts **static websites**
(because that's what you have just created with Jupyter Book). There are many options for doing this, and these sections cover some of the (because that's what you have just created with Jupyter Book). There are many options for doing this, and these sections cover some of the
more popular ones. more popular ones.
## Source vs build files
At this point, you have created a combination of Jupyter notebooks, markdown files, and configuration files, including `_toc.yml` and `_config.yml`.
These files are your __source__ files.
The __source__ files comprise all of the content and configuration that Jupyter Book needs to build your book.
The `_build` folder contains all of your static website __build__ files.
The __build__ files contain all of the output from Jupyter Book's `build` command.
These files are only used to view your content in a browser.
Best practice for publishing your book is to keep two branches in your git project:
- Your book's __source__ files that you create to build the book
- Your book's __build__ files that Jupyter Book created to view the book
(publish/online-repo)= (publish/online-repo)=
## Create an online repository for your book ## Create an online repository for your book
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment