Merge pull request #46 from TeachBooks/workshop-update

Workshop update

book/_config.yml

@@ -18,6 +18,7 @@ sphinx:
   - jupyterbook_patches
   - teachbooks_sphinx_grasple
   - sphinx_image_inverter
+  - sphinx_exercise
   config:
     html_js_files:
     - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js

book/_toc.yml

@@ -2,7 +2,21 @@ format: jb-book
 root: intro
 
 parts:
-  - caption: Getting started!
+  - caption: Your First TeachBook!
+    chapters:
+    - file: intro/book.md
+    - file: intro/workflow.md
+    - file: intro/template.md
+      sections:
+      - file: external/template/book/exercises/001.md
+      - file: external/template/book/exercises/002.md
+      - file: external/template/book/exercises/003.md
+      - file: external/template/book/exercises/004.md
+      - file: external/template/book/exercises/005.md
+      - file: external/template/book/exercises/006.md
+      - file: intro/workshop/summary
+    - file: intro/next.md
+  - caption: Getting Going!
     chapters:
     - file: installation-and-setup/user_types.md
     - file: installation-and-setup/git.md
@@ -13,7 +27,6 @@ parts:
       - file: installation-and-setup/anaconda.md
       - file: installation-and-setup/git_bash_conda_vs-code.md
       - file: installation-and-setup/jupyter-book-setup.md
-    - file: external/template/README.md
     - file: workflows/collaboration.md
       sections:
       - file: workflows/milestones_issues.md
@@ -40,6 +53,7 @@ parts:
         title: Banner or Announcement
     - file: features/easy-editing.md
       sections:
+      - file: external/template/README.md
       - file: features/teachbooks
       - file: external/deploy-book-workflow/README.md
       - file: features/local_server
@@ -85,7 +99,7 @@ parts:
     - file: examples/coding_theory_widgets.ipynb
     - file: examples/parametric_questions.ipynb
 
-  - caption: Editing tools
+  - caption: Editing Tools
     chapters:
     - file: tools/figmaker
     - file: helper_code/intro.md

book/external/template

@@ -1 +1 @@
-Subproject commit 3d424555e5c727db9e614e1004bd27899b51814b
+Subproject commit 4a5f1c8983241cc78d9fc91ba925d50402e9f558

book/installation-and-setup/tools.md

@@ -58,7 +58,7 @@ On GitLab a webserver is required to process book-changes online. Both we and ot
 ### Setting up book repository and website
 On GitHub you can start right away with a git environment and online book using our [template](../external/template/README.md).
 
-On GitLab you can set up your own git environment, but you need to be given access by [TeachBooks](mailto:teachbooks@tudelft.nl) or [TU Delft OIT](mailto:Interactive-textbooks@tudelft.nl) to view your build book online.
+On GitLab you can set up your own git environment, but you need to be given access by [TeachBooks](mailto:info@teachbooks.io) or [TU Delft OIT](mailto:Interactive-textbooks@tudelft.nl) to view your build book online.
 
 ### Book access with SSO
 When you’re releasing your book on a server on which you're in control (connected to GitLab or GitHub), you can set up SSO login for visitors of the website. This can be arranged for on the TeachBooks server.

book/intro.md

@@ -1,5 +1,19 @@
 # TeachBooks Manual
 
-This manual assists you in creating and collaborating on <a href="https://jupyterbook.org/"><img  style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="images/logo-wide.svg" alt="Jupyter book"></a> for educational purposes. Some parts are specifically aimed for teachers at Delft University of Technology, although all material and tools are openly available. This manual aims at providing an easy start and advanced usages for new and existing users with or without skills on this topic. it is part of TeachBooks, for more information visit [https://teachbooks.io/](https://teachbooks.io/).
+This manual is primarily designed for and by teachers for use in education, but should be a useful resource for anyone interested in creating and collaborating on <a href="https://jupyterbook.org/"><img  style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="images/logo-wide.svg" alt="Jupyter book"></a>. Our aim is to provide a simple way to start book-making for new users (it only takes 10 clicks!) through advanced usage for experienced users. We hope you find this resource useful and refer back to it often.
 
-Happy book building!
+TeachBooks originated at Delft University of Technology in the Netherlands, and some of the material in this Manual reflects tools and resources specific to TU Delft. With the exception of a few tools for which we have educational licenses at Delft, everything in this Manual is open source. Despite this, we are happy to grow our community beyond Delft and welcome contributions from all users.
+
+For more information about TeachBooks, visit [https://teachbooks.io/](https://teachbooks.io/). Do not hesitate to reach out via email at [info@teachbooks.io](mailto:teachbooks@tudelft.nl) or contribute on GitHub via discussions, issues or pull requests.
+
+Happy book building!
+
+## How to Use this Manual
+
+There are several "parts" to the manual:
+- **Your First TeachBook!** introduces the essential platforms and workflows, and contains a _workshop_ that can be completed independently or as part of a TeachBooks training. We recommend even experienced Jupyter Book users go through this material to better understand the TeachBooks vision on how to make books collaboratively, as this drives much of our tool development. The workshop is designed to be completed in 1-2 hours and does not require any prior knowledge or installation (just a GitHub account).
+- **Getting Going!** begins with an overview of _User Types_, which are used to help understand which parts of the Manual are most relevant to you. Detailed software installation instructions, book and team setup and workflows are also provided in this part.
+- The **Features** part describes a suite of tools that are useful for teachers, many of which are developed by TeachBooks contributors specifically for use in education. Many of these tools are illustrated in the **Examples**.
+- A few special tools are included in the **Editing Tools** that are useful when writing content.
+
+See the final chapters of this book (under **Miscellaneous**) for additional information about References, Credits, etc.

book/intro/book.md

@@ -0,0 +1,60 @@
+# What is a TeachBook?
+
+Never seen a TeachBook before? Here's a small demo of our MUDE-book!
+
+<div style="display: flex; justify-content: center;">
+    <div style="position: relative; width: 100%; height: 0; padding-bottom: 56.25%;">
+        <iframe
+            src="https://www.youtube.com/embed/gbBsWo6em4c?si=ayKhISsx06LmGbDD"
+            style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
+            frameborder="0"
+            allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+            allowfullscreen
+        ></iframe>
+    </div>
+</div>
+
+So what are you looking at? It's a website generated with the [Jupyter Book package](https://jupyterbook.org/). Various extensions have been added to improve the student-experience, especially for technical topics! The actual website you're looking at now is a JupyterBook. With TeachBooks we aim to make it easy to collaboratively use it, even if you've little experience with the software package which is part of it.
+
+The source files of this book consists of three parts:
+1. A configuration file to define functionalities, `_config.yml`
+2. A table of contents file to list which files should endup in the book, `_toc.yml`
+3. Content for your book! Text-based files which allows you to embed figures, videos, math and interactive elements.
+
+`````{admonition} Text-based files? yml? What is that?!
+:class: tip, dropdown
+
+Text-based files are digital files on your computer that you can open in a text editor and read directly. There are many file extensions used for text-based files, a few common ones related to Jupyter Book are: Markdown (`*.md`), Jupyter Notebooks (`*.ipynb`), and YAML (`*.yml`).
+
+YAML (or YML) is a text-based file format that is primarily used to store data. It is useful because it is easy for humans to read and write, and easy for machines to _parse_ and generate., which is why YAML is often used for configuration files. Here is an example of a YAML file...can you tell what information is being stored?
+
+```yaml
+parts:
+  - caption: Your First TeachBook!
+    chapters:
+    - file: intro/book.md
+    - file: intro/workflow.md
+    - file: intro/template.md
+      sections:
+      - file: external/teachbooks.md
+```
+
+````{admonition} Description of the YAML file
+:class: tip, dropdown
+
+You can see quite clearly that a number of files are listed, and that they are organized into chapters and sections. This defines the structure of the book---you can confirm this by comparing to the left sidebar, as this book is where this example YAML snippet came from!
+````
+`````
+
+A book is made by by writing content in text-based files such as Markdown (`*.md`), Jupyter Notebooks (`*.ipynb`), etc. After that, software is used to "parse" these files and create the final book (e.g., Jupyter Book)
+
+```{admonition} Comparing and Contrasting to LaTeX
+
+Have you ever used LaTeX? It turns out there are a lot of similarities with this document system. Here is a quick list:
+1. Writing "source code" in text-based files (i.e., `*.tex` versus `*.md`, `*.ipynb`, etc) that is generally easy to read without the markup and uses special functions to format rich document objects (e.g., tables, figures, etc).
+2. The "book" is created by using a piece of software that parses the source code and creates the final document (a `*.pdf` versus a `*.html` for Jupyter Book).
+3. Creating the document structure using a list of files that contain source code that automatically generates the Table of Contents and Index..
+4. Sometimes you can spend more time than you like troubleshooting "bugs" that turn out to be simple syntax errors.
+``` 
+
+Let's see how these books are made!

book/intro/next.md

@@ -0,0 +1,20 @@
+# You Know the Basics: What Next?
+
+You've seen what a JupyterBook is, how TeachBooks tries to help you with making those, and what the potential is in teaching. So what's next?
+
+In this manual we explain how to get going depending on the way you want to use it. If you successfully followed the steps until here, you'll be able to make book as a 'user type 3'!
+
+```{figure} ../installation-and-setup/figures/usertype3.jpg
+---
+name: usertype1
+width: 300px
+align: center
+---
+User type 3
+```
+
+In the next part of this manual 'Getting going!', we'll explain which options you have as more advanced user, how to collaboratively edit books en how to organize you team, tools, websites and copyright-considerations.
+
+Furthermore, in the 'Features' part we'll collect a suite of existing open-source software to ease the editing process, add functionalities, improve styling and improve the student-experience. Finally, the 'Examples' page contain some example pages of some book.
+
+We hope you enjoin making books with TeachBooks. If you encounter any problem, please reach out to us on [email](mailto:info@teachbooks.io) or our [GitHub Discussions](https://github.com/orgs/TeachBooks/discussions). We'd be happy to collaborate with you or simple receive some feedback, examples, cool ideas. Happy book building!

book/intro/template.md

@@ -0,0 +1,46 @@
+# It only takes 10 clicks!
+
+```{figure} figures/template.jpg
+---
+name: template
+width: 150px
+align: right
+```
+
+Now that you've been introduced to the basics of a Jupyter Book, let's make one! The TeachBooks Team has put together a set of tools to make the book-creation process as smooth and automatic as possible. This page guides you through the process of creating a book, followed by a series of exercises that are designed to help you get used to the syntax and structure of a Jupyter Book, as well as the tools and essential workflows associated with the editing, checking and review processes.
+
+## 1. Create a GitHub account
+TeachBooks relies of freely available services from GitHub to store files online, carry out the book-building process and host your book as a website. All you need to get started is a GitHub account (not counted in the 10 clicks 🤭).
+
+```{exercise}
+
+If you don't already have one, create a GitHub account here by visiting [github.com/signup](https://github.com/signup). 
+```
+
+## 2. Use the template---it's really just 10 clicks!
+Now, let's make a book: we've made a template on GitHub which carries out _most_ of the technical steps required to create a book and put it online. Instructions for using the template are in the `README` of the TeachBooks Template repository on GitHub, which is by default visible on the repository homepage.
+
+```{exercise}
+
+Go to the [TeachBooks Template repository on GitHub](https://github.com/TeachBooks/template) and follow the instructions to create your book. At the end, it should be visible at `<your_username>.github.io/<book>`. When finished, come back to this page.
+```
+
+## 3. Let's practice!
+Getting used to the syntax of writing in a Jupyter Book can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises have been prepared for you as part of an introductory **workshop**. The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages.
+
+```{exercise}
+Work through the exercises attached to this page (you can find them in the left sidebar). These exercises can also be found in the template book itself.
+```
+
+```{tip}
+Maybe you're already comfortable with Git, GitHub and the concept of using software to parse text-based files and create marked-up documents. In that case, can you answer the following questions (refering to the exercises):
+1. Can you add some content to the intro page?
+2. Can you add the file named `file_to_be_added_to_toc.md` to the book website?
+3. Can you edit the repository url defined in the `_config.yml`, change the title shown below the logo and change the author as shown in the footer?
+4. Can you make a new branch of your book with an additional file `file_on_new_version.md` and view it online?
+5. Can you merge your branch into `main` with a pull request?
+6. Can you fork someone else's repo, and suggest a change in a pull request?
+
+If something is not clear, dive into to the relevant exercise page.
+```
+

book/intro/workflow.md

@@ -0,0 +1,55 @@
+# How can you do it?
+
+The fun part is the collaborative aspect of TeachBooks! Because all the files are text-based, they're well suited for using git. That allows us to use the version-control principles of git to its best!
+
+Assuming you've a book (well make that happen soon!) and you're ready to collaborate, the process is as follows:
+
+## 1 get an idea
+```{figure} figures/idea.png
+---
+width: 70px
+align: right
+```
+You have an idea to improve a book or add some content! Let's make that happen! Share you idea with the book-authors to let them know you're starting something! Maybe someone else has some ideas on it as well. Later on, you can use GitHub `Issues`, `Projects` and `Milestones` to keep track of this.
+
+## 2 create your version of the book
+```{figure} figures/branch.png
+---
+width: 100px
+align: right
+```
+Let's create a space for you idea to form. You can create your own version of the book, visible for everyone to see. On GitHub, you'll use `branches` or `forks`.
+
+## 3 edit the book
+```{figure} figures/edit.png
+---
+width: 100px
+align: right
+```
+Creativity activated, let's start adding content to your book! You'll add text, images, videos, math, interactive quizes, coding, widgets, etc. As editing the book is not directly done in a graphical interface with buttons like Microsoft Word, you'll need to learn a bit of syntax. The [MyST syntax cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) will be added to your bookmarks. The changes you'll make have to be added to the GitHub version control system, creating `commits` on the your git `branch`.
+
+## 4 check changes
+```{figure} figures/check.png
+---
+width: 100px
+align: right
+```
+You've made a change, how does is look like? Your raw file have to be parsed. You can do that yourself or use the tooling provided by use in a GitHub `Action`. As soon as you uploaded (`pushed` in Git language) your changes to GitHub, it'll create a nice looking website for you!
+
+## 5 repeat, edit and check
+```{figure} figures/review.png
+---
+width: 100px
+align: right
+```
+You'll make mistakes and you'll want to alter content... many, many times... As long as your idea is not ready to be shared with other, keep iterating step 3 and 4 until it's perfect!
+
+## 6 submit for review
+```{figure} figures/online.png
+---
+width: 100px
+align: right
+```
+You're done! Great! Now let's see what others think of your contribution. You'll submit your changes to the original book, in GitHub language this is called a `Pull request`. Other will be able to review, adapt and eventually `merge` your version into the book!
+
+I hope that all of this seems fun! Let's continue on making this happen!

book/intro/workshop/06.md

@@ -0,0 +1,13 @@
+# Exercise 6: Submit for Review
+
+Now we make a PR and merge it.
+
+
+```{admonition} Check your understanding
+:class: tip
+
+Before moving on to the next exercise, make sure you understand the following:
+1. Where is the Table of Contents defined?
+...
+```
+

book/intro/workshop/07.md

@@ -0,0 +1,11 @@
+# Exercise 7: Collaborate
+
+Fork, PR, merge.
+
+```{admonition} Check your understanding
+:class: tip
+
+Before moving on to the next exercise, make sure you understand the following:
+1. What is a fork?
+...
+```

book/intro/workshop/summary.md

@@ -0,0 +1,21 @@
+# Summary of Workshop: All Exercises
+
+With the exercises, you did all the steps of our TeachBooks workflow!
+
+```{figure} ../figures/TeachBooks_flowchart_v04.png
+---
+width: 500px
+align: center
+---
+```
+
+Here is how the exercises relate to the workflow.
+
+| Step No. | Name | Exercise | Description |
+| :---: | :---: | :---: | :---: |
+| 1 | Get and idea | 4 | Create an issue |
+| 2 | Create _your_ version of the book | 4 | Create a branch |
+| 3 | Edit the book | 1, 2, 3| Editing `.md`-files, the `_toc.yml` and the `_config.yml` |
+| 4 | Check changes online | 1, 2, 3 | Workflows and Actions Summary |
+| 5 | Repeat edit and checking | 1, 2, 3, 4, 5 | Keep on doing all the steps until it's ready|
+| 6 | Submit for review | 5, 6 | Open and merge a Pull Request, from a branch or forks |

requirements.txt

@@ -11,4 +11,5 @@ sphinx-image-inverter
 --extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple
 sphinx-thebe ~= 0.9.9
 
-docutils==0.17.1
+docutils==0.17.1
+sphinx-exercise