From 75f902e5e3816b62b63ac2cfb07cc8da305691d9 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Tue, 11 Jul 2023 17:04:35 +0200 Subject: [PATCH] add local server instructions --- book/cookbook/grasple.md | 8 +++++++- .../jupyterlite/including-jupyterlite.md | 5 +++++ .../jupyter-book-setup.md | 20 ++++++++++++++++++- 3 files changed, 31 insertions(+), 2 deletions(-) diff --git a/book/cookbook/grasple.md b/book/cookbook/grasple.md index 19d27ae..1a598a3 100644 --- a/book/cookbook/grasple.md +++ b/book/cookbook/grasple.md @@ -7,7 +7,13 @@ The embed link is created for an exercise under 'More'- 'Embed Exercise' -This iframe can be embedded into your Jupyter book. Remark: it doesn't display locally in VScode or in the build file, only on the hosted version. The code shown above gives: +This iframe can be embedded into your Jupyter book. + +```{admonition} Note +:class: tip +This feature doesn't display in a book that is viewed locally via your browser, unless you set up a local webserver (instructions [here](setup-local-server)). +``` +The code shown above gives: More information on Grasple and the support of TU Delft can be found on: [Teaching Support - Educational Tools - Grasple](https://www.tudelft.nl/en/teaching-support/educational-tools/grasple) diff --git a/book/cookbook/jupyterlite/including-jupyterlite.md b/book/cookbook/jupyterlite/including-jupyterlite.md index 0d00108..6e3f569 100644 --- a/book/cookbook/jupyterlite/including-jupyterlite.md +++ b/book/cookbook/jupyterlite/including-jupyterlite.md @@ -9,6 +9,11 @@ There are three different `JupyterLite` directives that you can include in your Below are examples demonstrating how to include each variant. Note that the `jupyterlite-sphinx extension` is designed for use with `.rst` files (Restructured Text). Luckily, `MyST` provides a convenient directive that allows us to include Restructured Text content in a regular `.md` file. +```{admonition} Note +:class: tip +This feature doesn't display in a book that is viewed locally via your browser, unless you set up a local webserver (instructions [here](setup-local-server)). +``` + ## `retrolite` To embed a Jupyter Notebook environment in your book, include the following directive: diff --git a/book/installation-and-setup/jupyter-book-setup.md b/book/installation-and-setup/jupyter-book-setup.md index b9d7326..50e4247 100644 --- a/book/installation-and-setup/jupyter-book-setup.md +++ b/book/installation-and-setup/jupyter-book-setup.md @@ -4,4 +4,22 @@ Jupyter Book is just a regular Python package, so it can be installed by using ` pip install jupyter-book -Nevertheless, it's always a good idea make a fresh `conda` environment when starting a new project. \ No newline at end of file +Nevertheless, it's always a good idea make a fresh `conda` environment when starting a new project. + +## View the book locally + +Once the build process is completed successfully, you will see the file location in your terminal output. Simply open this in the browser (you may have to copy/paste). + +```{admonition} Tip +:class: tip, dropdown +Bookmark the (local) file location for easy access! +``` +(setup-local-server)= +## View the book using a local webserver + +Some features like JupyterLite and Grasple only work when a webserver serves the HTML content for a book. Rather than building the book in your repository and updating the website on the internet, you can use a local webserver to view the book: +1. Start a server from the command line with: `python -m http.server -b 127.0.0.1` (add ` &` if you want to keep using the terminal for other tasks). +2. Port 8000 is usually used by default, but depending on your OS it will tell you in the output. +3. To visit your site, just enter the address in your web browser, followed by a colon, and then the port number. By default, that would be: `127.0.0.1:8000`. +4. You will get a website that looks like a file browser, to visit your site just navigate to `book/_build/html/`. +5. The JupyterLite consoles or Grasple iframe exercises should now work as well.