diff --git a/book/_toc.yml b/book/_toc.yml index b7e9652..d122331 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -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 diff --git a/book/intro/workshop/01.md b/book/intro/workshop/01.md new file mode 100644 index 0000000..b066b6c --- /dev/null +++ b/book/intro/workshop/01.md @@ -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? +``` diff --git a/book/intro/workshop/02.md b/book/intro/workshop/02.md new file mode 100644 index 0000000..09184aa --- /dev/null +++ b/book/intro/workshop/02.md @@ -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? +... +``` + diff --git a/book/intro/workshop/03.md b/book/intro/workshop/03.md new file mode 100644 index 0000000..3e666fd --- /dev/null +++ b/book/intro/workshop/03.md @@ -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? +... +``` + diff --git a/book/intro/workshop/04.md b/book/intro/workshop/04.md new file mode 100644 index 0000000..0832334 --- /dev/null +++ b/book/intro/workshop/04.md @@ -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? +... +``` + diff --git a/book/intro/workshop/05.md b/book/intro/workshop/05.md new file mode 100644 index 0000000..0e48cd2 --- /dev/null +++ b/book/intro/workshop/05.md @@ -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? +... +``` + diff --git a/book/intro/workshop/06.md b/book/intro/workshop/06.md new file mode 100644 index 0000000..0691015 --- /dev/null +++ b/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? +... +``` + diff --git a/book/intro/workshop/07.md b/book/intro/workshop/07.md new file mode 100644 index 0000000..850b019 --- /dev/null +++ b/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? +... +``` \ No newline at end of file diff --git a/book/intro/workshop/summary.md b/book/intro/workshop/summary.md new file mode 100644 index 0000000..cfc2236 --- /dev/null +++ b/book/intro/workshop/summary.md @@ -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! \ No newline at end of file