Merge branch 'main' into 'publish'

Update deployment

See merge request interactivetextbooks-citg/jupyter-book-manual!31

.gitlab-ci.yml

@@ -32,35 +32,20 @@ test-build:
 
 build-book:
   stage: build
-  rules:
-    - if: $CI_COMMIT_BRANCH == "publish" && $CI_PIPELINE_SOURCE == "push"
-  before_script:
-    - python -V
-    - conda env create -f environment.yml
-    - conda init bash
-    - source ~/.bashrc
-    - conda activate jupyter-book-env
-  script:
-    - jupyter-book clean book/
-    - jupyter-book build book/
-  artifacts:
-    expire_in: 30 days
-    paths:
-      - book/_build/html/
-
-build-container:
   image: docker
-  stage: build
   rules:
     - if: $CI_COMMIT_BRANCH == "publish" && $CI_PIPELINE_SOURCE == "push"
-  needs:
-    - build-book
   before_script:
     - docker info
   script:
-    - docker build -t $TAG_COMMIT -t $TAG_LATEST .
-    - docker push $TAG_COMMIT
+    - docker build -t $TAG_LATEST
     - docker push $TAG_LATEST
-  environment:
-    name: production
-    url: https://interactivetextbooks.citg.tudelft.nl/
+
+deploy-book:
+  stage: deploy
+  image: docker
+  rules:
+    - if: $CI_COMMIT_BRANCH == "publish" && $CI_PIPELINE_SOURCE == "push"
+  script:
+    - docker compose -f /etc/web_server/docker-compose.yml pull
+    - docker compose -f /etc/web_server/docker-compose.yml up -d --no-deps manual

Dockerfile

@@ -1,3 +1,8 @@
-FROM httpd:latest
-
-COPY ./book/_build/html /usr/local/apache2/htdocs
+FROM continuumio/miniconda3
+WORKDIR /book
+COPY book/ .
+RUN apt-get update && apt-get -y install git gcc
+COPY requirements.txt requirements.txt
+RUN pip install -r requirements.txt
+RUN jupyter book build .
+ENTRYPOINT [ "python", "-m", "http.server", "8000", "--directory", "_build/html" ]

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:
 <iframe height="560" src="https://embed.grasple.com/exercises/767782d5-023a-4b49-a1f3-874fca626c8e?id=79907" title="Grasple Exercise 79907" width="100%" allow="clipboard-read; clipboard-write"></iframe>
 
 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)

book/cookbook/h5p.md

@@ -1,4 +1,4 @@
-# adding interactive h5p elements
+# Adding interactive h5p elements
 
 ## Instruction
 H5p elements are interactive HTML-blocks which can be imbeded in a Jupyter Book using an iframe. H5p element can be created in the [TU Delft portal on the H5p website](https://tudelft.h5p.com/content) (sign in via Brightspace to H5p required first). The iframe code can be copied at Edit - Publish - Public - Embed code. This html code can be directly added to your markdown file:

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:

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