diff --git a/.gitignore b/.gitignore index 375f4dc..eb99377 100644 --- a/.gitignore +++ b/.gitignore @@ -130,6 +130,7 @@ dmypy.json # Jupyter Book _build/ +_contents/ # Jupyterlite _output/ \ No newline at end of file diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index c27ed4e..a086873 100644 --- a/.gitlab-ci.yml +++ b/.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 \ No newline at end of file + 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 \ No newline at end of file diff --git a/book/_toc.yml b/book/_toc.yml index c788e1c..f6cbb07 100644 --- a/book/_toc.yml +++ b/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 \ No newline at end of file diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md new file mode 100644 index 0000000..1dd46cd --- /dev/null +++ b/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 `) +- 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) diff --git a/book/examples/overview.md b/book/examples/overview.md new file mode 100644 index 0000000..7de0ba3 --- /dev/null +++ b/book/examples/overview.md @@ -0,0 +1,3 @@ +# Overview + +This part will include examples for jupyter book pages with features \ No newline at end of file diff --git a/book/cookbook/grasple.md b/book/features/grasple.md similarity index 100% rename from book/cookbook/grasple.md rename to book/features/grasple.md diff --git a/book/cookbook/h5p.md b/book/features/h5p.md similarity index 100% rename from book/cookbook/h5p.md rename to book/features/h5p.md diff --git a/book/cookbook/jupyterlite/configuration.md b/book/features/jupyterlite/configuration.md similarity index 100% rename from book/cookbook/jupyterlite/configuration.md rename to book/features/jupyterlite/configuration.md diff --git a/book/cookbook/jupyterlite/including-jupyterlite.md b/book/features/jupyterlite/including-jupyterlite.md similarity index 100% rename from book/cookbook/jupyterlite/including-jupyterlite.md rename to book/features/jupyterlite/including-jupyterlite.md diff --git a/book/cookbook/jupyterlite/interactive-wave.ipynb b/book/features/jupyterlite/interactive-wave.ipynb similarity index 100% rename from book/cookbook/jupyterlite/interactive-wave.ipynb rename to book/features/jupyterlite/interactive-wave.ipynb diff --git a/book/cookbook/jupyterlite/jupyterlite-gallery.md b/book/features/jupyterlite/jupyterlite-gallery.md similarity index 100% rename from book/cookbook/jupyterlite/jupyterlite-gallery.md rename to book/features/jupyterlite/jupyterlite-gallery.md diff --git a/book/cookbook/jupyterlite/jupyterlite.md b/book/features/jupyterlite/jupyterlite.md similarity index 100% rename from book/cookbook/jupyterlite/jupyterlite.md rename to book/features/jupyterlite/jupyterlite.md diff --git a/book/cookbook/jupyterlite/wave.ipynb b/book/features/jupyterlite/wave.ipynb similarity index 100% rename from book/cookbook/jupyterlite/wave.ipynb rename to book/features/jupyterlite/wave.ipynb diff --git a/book/features/overview.md b/book/features/overview.md index 95824d8..51fb44a 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -1,4 +1,4 @@ -# Book Features +# CEG-book Features ```{warning} Under Construction! diff --git a/book/cookbook/recipes.md b/book/features/recipes.md similarity index 100% rename from book/cookbook/recipes.md rename to book/features/recipes.md diff --git a/book/installation-and-setup/overview.md b/book/installation-and-setup/overview.md new file mode 100644 index 0000000..a510dbd --- /dev/null +++ b/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. \ No newline at end of file diff --git a/book/intro.md b/book/intro.md index 3d79593..710a68a 100644 --- a/book/intro.md +++ b/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 `) -- 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 -``` -
- -
-``` -is not supported. but the `img` tag is: -``` - -``` -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. diff --git a/book/workflows/overview.md b/book/workflows/overview.md new file mode 100644 index 0000000..d77d16d --- /dev/null +++ b/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. \ No newline at end of file