Merge pull request #3 from eWaterCycle/make_teachbook

making repo into teachbook

.github/workflows/call-deploy-book.yml

@@ -0,0 +1,26 @@
+name: call-deploy-book
+
+on:
+  push:
+    branches:
+    - 'main'
+    - 'draft'
+    # If your git repository has the Jupyter Book within some-subfolder next to
+    # unrelated files, you can make this run only if a file within that specific
+    # folder (or the workflow file itself) has been modified.
+    #
+    paths:
+    - book/**
+    - requirements.txt
+    - .github/workflows/call-deploy-book.yml
+  workflow_dispatch:
+
+jobs: 
+  call-workflow:
+    uses: TeachBooks/deploy-book-workflow/.github/workflows/deploy-book.yml@main
+    secrets: inherit
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+

README.md

@@ -1,2 +1,55 @@
-# teaching-materials
-Teaching materials for the course "river basin hydrology" at TU Delft
+# Your first TeachBook using the GitHub template
+
+The template allows you to start your own TeachBook and hosting that TeachBook online without knowledge on Git, the Jupyter book package, python or anaconda. It doesn't elaborate on the collaborative functionalities of Git or how to edit the book. Please look at our manual (https://teachbooks.tudelft.nl/jupyter-book-manual) to find more about that!
+
+## Features
+- A github repository structure for making a [Jupyter Book](https://github.com/executablebooks/jupyter-book) (`/book`)
+- An empty TeachBook containing an intro page on root, an example markdown page, an example jupyter notebook page, an example references page. and an example credits page. (`/book/_toc.yml`, `/book/_config.yml`, `/book/credits.md`, `/book/intro.md`, `/book/references.md`, `/book/some_content/overview.md`, `/book/some_content/text_and_code.ipynb`)
+- A file ready for adding references (`references.bib`, `/book/references.md`)
+- An example favicon (web browser icon) (`/book/figures/favicon.ico`, `book/_config.yml`.)
+- An example logo (`/book/figures/TUDelft_logo_rgb.png`, `/book/config.yml`)
+- The configuration files set ready to make your Jupyter Notebooks pages work with [live code using our sphinx-thebe extension](https://teachbooks.tudelft.nl/jupyter-book-manual/features/live_code.html) and our recommended settings (`/book/config.yml`)
+- An example of setting up preprocessing your table of contents to hide certain draft chapters for eg. students (`_toc.yml`)
+- A file containing all the recommended software packages (`requirements.txt`)
+- A file containing the recommended license CC BY 4.0 (`LICENSE.md`)
+- Our [GitHub workflow for publishing your TeachBook to GitHub Pages](https://github.com/TeachBooks/deploy-book-workflow) (`.github/workflow/call-deploy-book.yml`)
+- A gitignore file containing standard python filetype to ignore (`.gitignore`)
+- A readme containing information how to use the template, which can adjusted after using the template (`README.md`)
+
+## How to get started
+
+How to use the template is demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial.
+
+![Demonstration for a public repository](figures/teachbooks-template.gif)
+Video available [here](https://youtu.be/nN3Oi_MVvF0)
+
+
+1. To get started making your TeachBook with our functionalities, use the [template TeachBook](https://github.com/TeachBooks/template) as template:
+
+![Use template](figures/use_template.png)
+
+2. Fill in a repository name, this name will be used in the future url of your book:
+
+![Create new repository](figures/create_new_repository.png)
+
+3. You can choose for `Private` only if you've GitHub Pro, GitHub Team, GitHub Enterprise Cloud, or GitHub Enterprise Server. Otherwise, you won't be able to publish your TeachBook online.
+
+4. (Only required for private repositories:) Create a Personal Access Token (classic) with at least the scopes `repo`, `read:org` and `gist` as described in the [github documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), and add this token with the name `GH_PAT` as a `Repository secret` or `Organization secret` (`Settings` > `Secrets and variables` > `Actions` > `Repository secrets` or `Organization secrets`).
+
+5. You need to activate GitHub pages so that your website is published to the internet. As long as you don't do this your TeachBook is not published online. Actually, now that you've taken this template our workflow tries to publish it to GitHub pages, which you didn't have the chance to activate yet. That's why you probably received an email with 'call-deploy-book: Some jobs were not successful' and you see the failed job under `Initial commit`. You can activate GitHub pages by setting the source for GitHub pages to GitHub Actions under `Settings` - `Pages` - `Build and deployment` - `Source` - `GitHub Actions`:
+
+![Activate GitHub Pages](figures/set_up_pages.png)
+
+6. Make an edit to the TeachBook by editing and committing changes to one of the files in the `book/` subdirectory (available under `Code`).  Now checkout the progress of the publishing workflow under `Actions` - `All workflows` -  `call-deploy-book` -`<the most recent workflow run>`. Remember, the first commit which is there has failed because GitHub Pages wasn't activated at the time of `Initial commit`, you could also re-run that job if you don't want to make an edit. You can do so by running the workflow from `Actions` - `All workflows` - `call-deploy-book` - `Initial commit` - `Re-run all jobs` - `Re-run jobs`:
+
+![Action](figures/action_re-run.jpeg)
+
+7. When the workflow has finished, visit your build TeachBook at `https://<username or organiszation_name>.github.io/<repository_name>` (case sensitive). For our example it is [https://dummydocent.github.io/test_book_from_template/](https://dummydocent.github.io/test_book_from_template/) for the shown repository. These links are visible in the action's summary as well, as shown in the figure of step 4.
+
+Additional tip: 
+Set the repository website as your GitHub Pages website under `Code`- `About` - `Settings icon` - `Website` - `Use your GitHub Pages Website`
+
+![GitHub pages as website](figures/use_github_pages_website.png)
+
+## Contribute
+This tool's repository is stored on [GitHub](https://github.com/TeachBooks/template). The `README.md` of the branch `manual_description` is also part of the [TeachBooks manual](https://teachbooks.tudelft.nl/jupyter-book-manual/external/template/README.html) as a submodule. If you'd like to contribute, you can create a fork and open a pull request on the [GitHub repository](https://github.com/TeachBooks/template). To update the `README.md` shown in the TeachBooks manual, create a fork and open a merge request for the [GitLab repository of the manual](https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual). If you intent to clone the manual including its submodules, clone using: `git clone --recurse-submodules [email protected]:interactivetextbooks-citg/jupyter-book-manual.git`.

book/_config.yml

@@ -0,0 +1,37 @@
+title: Template
+author: TeachBooks Team, built with <a href="https://teachbooks.tudelft.nl/">TeachBooks</a> and <a href="https://jupyterbook.org/">Jupyter Book</a>, <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer"">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt=""></a> #add your own name here
+logo: figures/TB_logo.png #add your own logo here
+
+execute:
+  execute_notebooks: "off"
+
+only_build_toc_files: true
+
+html:
+  favicon : "figures/TB_favicon.ico"
+  baseurl :  "https://teachbooks.github.io/template/" #Replace this with your own URL
+
+sphinx:
+  config:
+    html_js_files:
+    - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js
+    thebe_config:
+      use_thebe_lite: true
+      exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"]
+    html_theme_options:
+      repository_url: "https://github.com/TeachBooks/template" #add your own repo URL here
+      use_repository_button: true
+      use_issues_button : true
+      launch_buttons:
+        thebe: true
+    html_show_copyright: false
+    html_last_updated_fmt: '%B %-d, %Y'
+  extra_extensions:
+    - sphinx.ext.imgconverter
+    - jupyterbook_patches
+    - download_link_replacer
+    - sphinx.ext.extlinks
+    - sphinx_image_inverter
+
+bibtex_bibfiles: 
+  - references.bib

book/_toc.yml

@@ -0,0 +1,12 @@
+format: jb-book
+root: intro.md
+
+parts:
+  - caption: Contents
+    chapters:
+    - file: some_content/overview.md
+      sections:
+      - file: some_content/text_and_code.ipynb
+    - file: references.md
+    - file: changelog.md
+    - file: credits.md

book/changelog.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## `<date>` [`<release name>`](<`link to release on GitHub>`)
+- `<Added/modified/deleted>` [](`<relative link to changed file>`)

book/credits.md

@@ -0,0 +1,25 @@
+(credits)=
+# Credits and License
+
+You can refer to this book as:
+
+> `<editors>` (`<year>`) _`<title>`_. `<url to github repo>`
+
+The introduction, structure of the book and formatting of contents is done by the Editors. Some chapters and pages have additional primary authors who are identified within the book either at the bottom of the first page in a chapter, or at the bottom of an individual page, as necessary. If an author is not listed on a particular page, it is by the Editors.
+
+You can refer to individual chapters or pages within this book as:
+
+> `<Primary Author>` (`<date>`) `<Title of Chapter or Page>`. In `<editors>` (Ed.), _`<title>`_. `<url to github repo>`
+
+We anticipate that the content of this book will change significantly. Therefore, we recommend using the source code directly with the citation above that refers to the GitHub repository and lists the date and name of the file. Although content will be added over time, chapter titles and URL's in this book are expected to remain relatively static. However, we make no guarantee, so if it is important for you to reference a specific location within the book. For example:
+
+> `<Primary Author>` (`<date>`) `<Title of Chapter or Page>`. In `<editors>` (Ed.),  _`<title>`_. `<url to github repo>` (`./book/intro/` chapter, accessed November, 2024).
+
+## How the book is made
+
+This book is created using open source tools: it is a Jupyter Book that is written using Markdown, Jupyter notebooks and Python files to generate some figures. The files are stored on a [public GitHub repository](`<link to GitHub repo>`). The website can be viewed at `<link to book website url>`. View the repository README file or contact the authors for additional information.
+
+(editor)=
+## About the Editors
+
+### Acknowledgements

book/intro.md

@@ -0,0 +1,6 @@
+(intro)=
+# Welcome to the Template Book
+
+_Write book intro here. This is the first page the student will see when opening the url._
+
+This book can be used as a template for other books. It includes a starter package of the software developed by the TeachBooks initiative.

book/references.bib

@@ -0,0 +1,6 @@
+@misc{jason_moore,
+  title={Learn Multibody Dynamics, SymPy},
+  author={Moore, Jason},
+  howpublished={\url{https://moorepants.github.io/learn-multibody-dynamics/sympy.html}},
+  year={2023}
+}

book/references.md

@@ -0,0 +1,3 @@
+# References
+:::{bibliography}
+:::

book/some_content/overview.md

@@ -0,0 +1,3 @@
+# Overview
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

book/some_content/text_and_code.ipynb

@@ -0,0 +1,51 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Text and code\n",
+    "\n",
+    "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "hello world\n"
+     ]
+    }
+   ],
+   "source": [
+    "print('hello world')"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "base",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.18"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

requirements.txt

@@ -0,0 +1,9 @@
+# first list the packages you wish to download from PyPI
+teachbooks # depends on jupyter-book
+jupyterbook-patches
+sphinx-image-inverter
+download_link_replacer
+
+# now list the packages (and the respective url) you wish to download from the GitLab package registry
+--extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple
+sphinx-thebe ~= 0.9.9