📚 DOCS: update instructions for using w/ jupyterhub and binder (jupyter-book#1097)

Author: cooperrc

docs/interactive/launchbuttons.ipynb

@@ -19,7 +19,21 @@
     "  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",
+    "The `repository:` configuration line uses `url`, `path_to_book`, and `branch` to find your notebook\n",
+    "files.  \n",
+    "\n",
+    "- The `url` should be a GitHub repository that includes your source files used to build the\n",
+    "  Jupyter Book. Your repository should include:\n",
+    "    - `_config.yml`\n",
+    "    - `_toc.yml`\n",
+    "    - `requirements.txt`: packages for binder or general reproducibility\n",
+    "    - _the source files in *.ipynb and *.md_\n",
+    "- The `path_to_book` should used if your book is in a sub-folder of your repository (e.g. `docs/` or\n",
+    "  `book/`)\n",
+    "- The `branch` should be the branch where your book's source files are stored. It _should not be_\n",
+    "  the [`gh-pages` branch](https://jupyterbook.org/publish/gh-pages.html). \n"
    ]
   },
   {
@@ -37,7 +51,8 @@
     "```\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). You then have two options:\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\"."
@@ -65,7 +80,8 @@
     "```\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."
+    "will insert Binder links to any pages that were built from notebook content.\n",
+    "\n"
    ]
   },
   {
@@ -74,22 +90,29 @@
    "source": [
     "## JupyterHub buttons for your pages\n",
     "\n",
-    "JupyterHub lets you host an online service that gives users their own Jupyter servers\n",
-    "with an environment that you specify for them. It allows you to give users access to\n",
-    "resources and hardware that you provision in the cloud, and allows you to authenticate users\n",
-    "in order to control who has access to your hardware.\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\n",
-    "your readers to a JupyterHub that is running a live, interactive version of your page. This\n",
-    "is accomplished using the [nbgitpuller](https://github.com/jupyterhub/nbgitpuller) server\n",
-    "extension.\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\n",
-    "such as [zero to jupyterhub for kubernetes](https://z2jh.jupyter.org) or [the littlest jupyterhub](https://tljh.jupyter.org)) with the following configuration:\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",
     "```"
    ]
   },
@@ -99,7 +122,8 @@
    "source": [
     "## {term}`Google Colab` buttons for your pages\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/). When a user clicks the button, they'll be taken to a live version of the page.\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",

docs/start/publish.md

@@ -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
 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)=
 ## Create an online repository for your book