{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Launch into interactive computing interfaces\n", "\n", "Because Jupyter Books are built with Jupyter notebooks, you can allow users to launch live Jupyter sessions in the cloud directly from your book.\n", "This lets readers quickly interact with your content in a traditional coding interface.\n", "They do so by clicking a **Launch Button** that takes them to an interactive environment.\n", "\n", "There are 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.\n", "\n", "(launchbuttons/configuration)=\n", "## Common launch button configuration\n", "\n", "In the case of each interactive service, you'll need to tell Jupyter Book where your book content lives online.\n", "To do so, use this configuration in `_config.yml`:\n", "\n", "```yaml\n", "# Information about where the book exists on the web\n", "repository:\n", " url : https://github.com/yourusername/yourbookrepo # Online location of your book\n", " path_to_book : path/to/book # Optional path to your book, relative to the repository root\n", " branch : master # Which branch of the repository should be used when creating links (optional)\n", "```\n", "\n", "A quick description of each option is below:\n", "\n", "`url`:\n", " A GitHub repository that includes your source files used to build the Jupyter Book.\n", " These files can either be in the root of the repository, or in a sub-folder (in which case you should use `path_to_book`).\n", "\n", "`path_to_book`:\n", " A path, relative to your repository's root, to your book's source files.\n", " Use this if your book is in a sub-folder of your repository (e.g. `docs/` or `book/`).\n", "\n", "`branch`:\n", " The branch where your book's **source files** are stored (not your book's _build files_, which generally exist in `gh-pages/` branch)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Control the notebook interface that opens\n", "\n", "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).\n", "This is configured using:\n", "\n", "```yaml\n", "launch_buttons:\n", " notebook_interface: \"jupyterlab\" # or \"classic\"\n", "```\n", "\n", "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.\n", " 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).\n", "You then have two options:\n", "\n", "- Use the \"classic\" interface, which will then immediately open these files as notebooks.\n", "- 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", "metadata": {}, "source": [ "(launchbuttons/binder)=\n", "## Add a Launch on {term}`Binder` button\n", "\n", "{term}`BinderHub` can be used to build the environment needed to run a repository, and provides\n", "a link that lets others interact with that repository. If your Jupyter Book is hosted online\n", "on GitHub, you can automatically insert buttons that link to the Jupyter Notebook running in a BinderHub.\n", "When a user clicks the button, they'll be taken to a live version of the page. If your code\n", "doesn't require a significant amount of CPU or RAM, you can use the free, public BinderHub running\n", "at https://mybinder.org.\n", "\n", "To automatically include Binder link buttons in each page of your Jupyter Book, use the following\n", "configuration in `_config.yml`:\n", "\n", "```yaml\n", "launch_buttons:\n", " binderhub_url: \"https://mybinder.org\" # The URL for your BinderHub (e.g., https://mybinder.org)\n", "```\n", "\n", "By adding this configuration, along with the repository url configuration above, Jupyter Book\n", "will insert Binder links to any pages that were built from notebook content.\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Add a Launch on {term}`JupyterHub` button\n", "\n", "JupyterHub lets you host an online service that gives users their own Jupyter servers with an environment that you specify for them.\n", "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.\n", "\n", "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.\n", "This is accomplished using the [nbgitpuller](https://github.com/jupyterhub/nbgitpuller) server extension.\n", "\n", "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:\n", "\n", "```yaml\n", "launch_buttons:\n", " jupyterhub_url: \"your-hub-url\" # The URL for your JupyterHub. (e.g., https://datahub.berkeley.edu)\n", "```\n", "\n", "On your JupyterHub server, you need two dependencies installed:\n", "1. To clone the notebook with the launch link, the server needs\n", "[`nbgitpuller`](https://jupyterhub.github.io/nbgitpuller/). \n", "\n", "2. To open myst-markdown as notebooks, the server needs\n", "[`jupytext>=0.16`](https://jupytext.readthedocs.io/en/latest/formats.html#myst-markdown). \n", "\n", "You can add the following line to your `DockerFile`:\n", "```\n", "RUN pip install jupytext nbgitpuller\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Add a Launch on {term}`Google Colab` button\n", "\n", "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/).\n", "When a user clicks the button, they'll be taken to a live version of the page.\n", "\n", "Similar to Binder link buttons, you can automatically include Google Colab link buttons with the following configuration in `_config.yml`:\n", "\n", "```yaml\n", "launch_buttons:\n", " colab_url: \"https://colab.research.google.com\"\n", "```\n", "\n", "```{note}\n", "Google Colab links will only work for pages that have the `.ipynb` extension.\n", "```" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.7.3" }, "widgets": { "application/vnd.jupyter.widget-state+json": { "state": {}, "version_major": 2, "version_minor": 0 } } }, "nbformat": 4, "nbformat_minor": 4 }