admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-12 22:35:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

add workshop exercises

Browse source
This commit is contained in:
Robert Lanzafame 2024-12-12 05:45:39 +01:00
parent 4a4c3ded43
commit dcbe6bd1ce
9 changed files with 206 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

24
book/_toc.yml
View file

@ -2,13 +2,31 @@ format: jb-book
root: intro
parts:
- caption: Your first TeachBook!
- caption: Your First TeachBook!
chapters:
- file: intro/book.md
- file: intro/workflow.md
- file: intro/template.md
sections:
- file: intro/workshop/01
title: "1: Edit Contents"
- file: intro/workshop/02
title: "2: How it's Made"
- file: intro/workshop/03
title: "3: Change Metadata"
- file: intro/workshop/04
title: "4: Online Editor"
- file: intro/workshop/05
title: "5: Your Version"
- file: intro/workshop/06
title: "6: Submit for Review"
- file: intro/workshop/07
title: "7: Collaborate"
- file: intro/workshop/summary
title: "Summary"
- file: intro/next.md
- caption: Getting going!
title: "What Next?"
- caption: Getting Going!
chapters:
- file: installation-and-setup/user_types.md
- file: installation-and-setup/git.md
@ -91,7 +109,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

13
book/intro/workshop/01.md Normal file
View file

@ -0,0 +1,13 @@
# Exercise 1: Edit Contents
the most basic edit: add something to intro.md and see that it is updated.
```{admonition} Check your understanding
:class: tip
Before moving on to the next exercise, make sure you understand the following:
1. Where are the contents of the book stored?
2. How can you edit a single file via the GitHub browser interface?
3. What is a commit and what role does it play in the editing process?
4. Given a specific GitHub repository, can you determine the URL of the book website?
```

16
book/intro/workshop/02.md Normal file
View file

@ -0,0 +1,16 @@
# Exercise 2: How it's Made
The first exercise edited book content. This exercise introduces GitHub Actions, workflows and how these tools are leveraged to create an automatic and effective book editing, checking and review process.
- introduce Actions briefly
- read stuff in the repo and identify key things
- come back here and answer some H5p questions?
```{admonition} Check your understanding
:class: tip
Before moving on to the next exercise, make sure you understand the following:
1. Where is the book metadata stored?
...
```

16
book/intro/workshop/03.md Normal file
View file

@ -0,0 +1,16 @@
# Exercise 3: Change Metadata
The first exercise edited book content. This exercise focuses on another of the three key ingredients, the configuration file `_config.yml`.
- make edits to the config file
- visit the Actions page and see the build process
- check that changes are incorporated (title, author, github link, etc)...could have a checklist
```{admonition} Check your understanding
:class: tip
Before moving on to the next exercise, make sure you understand the following:
1. Where is the book metadata stored?
...
```

14
book/intro/workshop/04.md Normal file
View file

@ -0,0 +1,14 @@
# Exercise 4: Online Editor
"Visual Studio Code for the Web" editor (VSC Web)
https://code.visualstudio.com/docs/editor/vscode-web
```{admonition} Check your understanding
:class: tip
Before moving on to the next exercise, make sure you understand the following:
1. Where is the book metadata stored?
...
```

12
book/intro/workshop/05.md Normal file
View file

@ -0,0 +1,12 @@
# Exercise 5: _Your_ Version of the Book
Branching
```{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?
...
```

13
book/intro/workshop/06.md Normal file
View file

@ -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?
...
```

11
book/intro/workshop/07.md Normal file
View file

@ -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?
...
```

90
book/intro/workshop/summary.md Normal file
View file

@ -0,0 +1,90 @@
# Summary of Workshop: All Exercises
This page gives an overview of exercises and tasks on the previous pages as part of the workshop.
```{tip}
Are you already comfortable with Git, GitHub and the concept of using software to parse text-based files and create marked-up documents? Then you can try completing the exercises by following the steps as outlined below. If something is not clear, refer back to the relevant exercise page.
```
## TeachBooks Workflow
Table overview:
Workflow Steps (DIAGRAM TO SIDE?)
Here is how the exercises relate to the workflow.
| Step No. | Name | Exercise | Description |
| :---: | :---: | :---: | :---: |
| 1 | Get and idea | N/A | |
| 2 | Create _your_ version of the book | 5 | Create a branch |
| 3 | Edit the book | 1, 3, 4, 5 | Several ways to do this |
| 4 | Check changes online | 2, 5 | Workflows and Actions Summary |
| 5 | Repeat edit and checking | N/A | |
| 6 | Submit for review | 6, 7 | Open and merge a Pull Request. Forks and PR's. |
## Overview of Exercises and Tasks
### Exercise 0: Preparation
The exercises here assume you have created a book using the TeachBooks Template repository on GitHub. If you haven't done this yet, please go back to the page [It only takes 10 clicks!](template.md) page.
### Exercise 1: Edit Contents
- Use the GitHub browser interface to edit a single file in your book.
- Make a commit to save your changes.
- Check that the changes are reflected in the book website.
### Exercise 2: How it's Made
- Visit the GitHub Actions tab in your repository.
- Identify the key jobs that make up the entire workflow
- Read the summary page and answer the H5p questions.
### Exercise 3: Metadata
- Use the GitHub browser interface to edit the `_config.yml` file.
- Visit the Actions page and watch the build process
- Open the job and see the command line output
- Once the job is complete, check that the changes are incorporated in the book website.
### Exercise 4: Online Editor
- Open the "Visual Studio Code for the Web" editor (VSC Web) using the shortcut `.` from your repository homepage
- Explore the file structure of your book
- Explore the editor interface, for example, use side-by-side file editing; look at the git tab
- Open multiple files and make changes to them
- Commit your changes using a single commit
- Check that the changes are reflected in the book website.
### Exercise 5: _Your_ Version of the Book
- Create a branch
- Open VSC Web editor
- Open the `_toc.yml` file and replace one page with another
- Commit your changes
- Visit the Actions to see results
- Open both versions of the book and confirm that the changes made in your branch are visible
- Confirm that the URL's of each book match the branch names
### Exercise 6: Submit for Review
- Open a Pull Request (GitHub will often prompt you to do this)
- Review the changes in the "Files changed" tab (note the commit summary also)
- Pretend that you are another team member (reviewer) and leave a comment
- Merge pull request
- Check Actions tab to see the workflow run
- Delete branch
### Exercise 7: Collaborate
- find a partner
- go to their repo and create a fork
- make a change to their book
- open a pull request, taking care that your forked repo/branch will be merged into their repo/branch (base)
- ask your partner to review and merge the pull request
- do the same for your partner in your repository
### Exercise n
Form your team, study the Manual, work on your book, enjoy!