Merge branch 'main' into 'publish'

New structure

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

.gitignore

@@ -130,6 +130,7 @@ dmypy.json
 
 # Jupyter Book
 _build/
+_contents/
 
 # Jupyterlite
 _output/

.gitlab-ci.yml

@@ -1,5 +1,3 @@
-image: continuumio/miniconda:latest
-
 stages:
   - test
   - build
@@ -9,8 +7,8 @@ variables:
   PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
   REGISTRY_HOST: localhost:5000
   TAG_LATEST: $REGISTRY_HOST/$CI_PROJECT_NAME/$CI_COMMIT_REF_NAME:latest
-  TAG_COMMIT: $REGISTRY_HOST/$CI_PROJECT_NAME/$CI_COMMIT_REF_NAME:$CI_COMMIT_SHORT_SHA
-  
+  TAG_DRAFT: $REGISTRY_HOST/$CI_PROJECT_NAME-draft/$CI_COMMIT_REF_NAME:latest
+
 cache:
   paths:
     - .cache/pip
@@ -18,31 +16,33 @@ cache:
 # This job tests if the book compiles gracefully after a new addition
 test-build:
   stage: test
+  image: continuumio/miniconda3
   rules:
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
-    - if: $CI_COMMIT_BRANCH == "main" && $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:
+    - pip install -r requirements.txt
     - jupyter-book clean book/
     - jupyter-book build book/
 
+# This job builds the Docker container
 build-book:
   stage: build
   image: docker
   rules:
     - if: $CI_COMMIT_BRANCH == "publish" && $CI_PIPELINE_SOURCE == "push"
+      variables:
+        TAG: $TAG_LATEST
+    - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push"
+      variables:
+        TAG: $TAG_DRAFT
   before_script:
     - docker info
   script:
-    - docker build -t $TAG_LATEST .
-    - docker push $TAG_LATEST
-    - docker image prune -f
+    - if [ "$TAG" = "$TAG_LATEST" ]; then sed --in-place=".bak" '/# START DRAFT/,/# END DRAFT/{//!d}' book/_config.yml; fi
+    - docker build -t $TAG .
+    - docker push $TAG
 
+# This job takes down the existing container and starts the new one
 deploy-book:
   stage: deploy
   image: docker
@@ -51,9 +51,25 @@ deploy-book:
   before_script:
     - docker info
     - docker stop $CI_PROJECT_NAME || exit_code=$?
-    - if [ $exit_code -ne 0 ]; then echo "Container $CI_PROJECT_NAME not found, cannot stop"; else docker rm $CI_PROJECT_NAME; fi
+    - if [ $exit_code -ne 0 ]; then echo "Container not found, cannot stop"; else docker rm $CI_PROJECT_NAME; fi
   script:
-    - docker run -d --restart always -p 8000:8000 --name $CI_PROJECT_NAME $TAG_LATEST
+    - docker run -d --restart always -p 8000:8000 --name $CI_PROJECT_NAME $TAG_LATEST # Make sure to use a different port for each book!
   environment:
     name: production
-    url: https://interactivetextbooks.citg.tudelft.nl/$CI_PROJECT_NAME
+    url: https://interactivetextbooks.citg.tudelft.nl/jupyter-book-manual
+
+# Deploy the draft version of the book
+deploy-draft:
+  stage: deploy
+  image: docker
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push"
+  before_script:
+    - docker info
+    - docker stop $CI_PROJECT_NAME-draft || exit_code=$?
+    - if [ $exit_code -ne 0 ]; then echo "Container not found, cannot stop"; else docker rm $CI_PROJECT_NAME-draft; fi
+  script:
+    - docker run -d --restart always -p 8018:8000 --name $CI_PROJECT_NAME-draft $TAG_DRAFT
+  environment:
+    name: draft
+    url: https://interactivetextbooks.citg.tudelft.nl/jupyter-book-manual-draft

book/_toc.yml

@@ -2,35 +2,39 @@ format: jb-book
 root: intro
 
 parts:
-  - caption: Installation and Setup
+  - caption: How to (start to) work and collaborate on your book
     chapters:
-    - file: installation-and-setup/git-setup
-    - file: installation-and-setup/vscode-setup
-    - file: installation-and-setup/jupyter-book-setup
+    - file: installation-and-setup/overview
+      sections:
+      - file: installation-and-setup/git-setup
+      - file: installation-and-setup/vscode-setup
+      - file: installation-and-setup/jupyter-book-setup
+    - file: workflows/overview
+      sections:
+      - file: workflows/git-basic
+        sections:
+        - file: workflows/git-clone
+        - file: workflows/git-branch
+        - file: workflows/git-stage-commit-push
+        - file: workflows/git-merge
+        - file: workflows/git-advanced
+          sections: 
+          - file: workflows/git-merge-conflict
+      - file: workflows/gitlab
   - caption: Features
     chapters:
-    - file: features
+    - file: basic-features/overview
+    - file: features/overview
       sections:
       - file: features/hypothesis
       - file: features/remove_from_publish
-  - caption: Workflows
+      - file: features/recipes.md
+      - file: features/grasple.md
+      - file: features/jupyterlite/jupyterlite
+        sections:
+        - file: features/jupyterlite/configuration
+        - file: features/jupyterlite/including-jupyterlite
+      - file: features/h5p.md
+  - caption: Examples
     chapters:
-    - file: workflows/git-basic
-      sections:
-      - file: workflows/git-clone
-      - file: workflows/git-branch
-      - file: workflows/git-stage-commit-push
-      - file: workflows/git-merge
-      - file: workflows/git-advanced
-        sections: 
-        - file: workflows/git-merge-conflict
-    - file: workflows/gitlab
-  - caption: Cookbook
-    chapters:
-    - file: cookbook/recipes.md
-    - file: cookbook/grasple.md
-    - file: cookbook/jupyterlite/jupyterlite
-      sections:
-      - file: cookbook/jupyterlite/configuration
-      - file: cookbook/jupyterlite/including-jupyterlite
-    - file: cookbook/h5p.md
+    - file: examples/overview

book/basic-features/overview.md

@@ -0,0 +1,11 @@
+# Basic Features
+
+```{warning} Under Construction!
+
+This page will provide a list of some commonly used book features which are all available in the original jupyter book package. However, this page includes best-practises on how to use them.
+```
+
+Things to include somewhere:
+- use the right HTML tags for images (described {ref}`here <image-tag-example>`)
+- watch out for `png` versus `PNG`
+- 2 interesting comments from Quinten about MyST extensions in [this GL Issue](https://gitlab.tudelft.nl/mude/archive-2022/-/issues/25#note_163123)

book/examples/overview.md

@@ -0,0 +1,3 @@
+# Overview
+
+This part will include examples for jupyter book pages with features

book/features/overview.md

@@ -1,4 +1,4 @@
-# Book Features
+# CEG-book Features
 
 ```{warning} Under Construction!
 

book/installation-and-setup/overview.md

@@ -0,0 +1,11 @@
+# Installation and setup
+
+```{warning} Under Construction!
+
+This page will provide a list of steps on how to install and setup the software you need to start working on your jupyter book:
+- the purpose
+- how to install them
+- how to use them
+- where to find the source code
+
+It will descirbe some steps for different user types.

book/intro.md

@@ -6,27 +6,7 @@ This is an introduction to Git, VS Code and Jupyter Books for teachers and teach
 
 Robert created this list to keep track of things that should be in our manual. Especially the small problems we have run into in MUDE and other projects.
 
-- use the right HTML tags for images (described {ref}`here <image-tag-example>`)
-- watch out for `png` versus `PNG`
-- trick for creating download link for PDFs (see Archive weekly summary pages); requires an `eval-rst` admonition, which can't be placed inside some objects (maybe someone can test this, and see if an inline option is available)
-- 2 interesting comments from Quinten about MyST extensions in [this GL Issue](https://gitlab.tudelft.nl/mude/archive-2022/-/issues/25#note_163123)
 
-(image-tag-example)=
-### Example of image tag
-
-This was found in the MUDE Archive, [Issue 29](https://gitlab.tudelft.nl/mude/archive-2022/-/issues/29).
-
-It looks like the `figure` tag
-```
-<figure>
-  <IMG SRC='...'>
-</figure>
-```
-is not supported. but the `img` tag is:
-```
-<img src="...">
-```
-see examples [here](https://jupyterbook.org/en/stable/content/figures.html) (no `figure` tag mentioned for HTML, only Markdown) 
 
 ## Contact
-If you encouter any issues, please contact Caspar Jungbacker (c.a.a.jungbacker@tudelft.nl).
+If you encouter any issues, please contact Tom van Woudenberg, Robert Lanzafame or one of our TAs Caspar Jungbacker or Julie Kirsch at books-CEG@tudelft.nl.

book/workflows/overview.md

@@ -0,0 +1,5 @@
+# Workflows
+
+```{warning} Under Construction!
+
+This page will provide a workflow how to collaborate in Git and GitLab for different uses types. Every team might have a different workflow but this workflow is shown as an example and is used in the MUDE course in CEG.