mirror of
https://github.com/TeachBooks/template.git
synced 2026-11-12 22:25:52 +00:00
Made it TU Delft specific
This commit is contained in:
Tom van Woudenberg
parent
060cd74e6a
commit
1da4cf05c4
16 changed files with 50 additions and 183 deletions
26
README.md
26
README.md
|
|
@ -1,8 +1,10 @@
|
|||
# Your first TeachBook using the GitHub template
|
||||
# Your first open interactive textbook using the GitHub template
|
||||
|
||||
[](https://github.com/TeachBooks/template/actions/workflows/call-deploy-book.yml)
|
||||
|
||||
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.io/manual) to find more about that!
|
||||
> This page reuses CC BY 4.0 licensed content from https://github.com/TeachBooks/template.
|
||||
|
||||
The template allows you to start your own open interactive textbook and hosting that textbook 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 the TeachBooks manual (https://teachbooks.io/manual) to find more about that!
|
||||
|
||||
## How to get started
|
||||
|
||||
|
|
@ -12,29 +14,29 @@ How to use the template is demonstrated in the figure below, all steps are elabo
|
|||
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:
|
||||
1. To get started making your open interactive textbook with our functionalities, use the [TU Delft template](https://github.com/TUDelft-books/TUDelft-template) as template:
|
||||
|
||||
|
||||
|
||||
2. Fill in a repository name, this name will be used in the future url of your book:
|
||||
2. Fill in a repository name, this name will be used in the future url of your book. If you're a member of the [TUDelft-books GitHub Organization](https://github.com/TUDelft-books) you can add your book directly to that organization to have it hosted on oit.tudelft.nl
|
||||
|
||||
|
||||
|
||||
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. Furthermore, it prevents people from contributing to your book, making your book essentially 'closed' instead of 'open.
|
||||
3. You can choose for `Private` only when you're a member of the [TUDelft-books GitHub Organization](https://github.com/TUDelft-books) and whenever that organization is one the TU Delft GitHub Enterprise account (which it's not yet at the moment). Otherwise, you won't be able to publish your open interactive textbook online. Furthermore, it prevents people from contributing to your book, making your book essentially 'closed' instead of 'open.
|
||||
|
||||
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`:
|
||||
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 open interactive textbook 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`:
|
||||
|
||||
|
||||
|
||||
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`:
|
||||
6. Make an edit to the open interactive textbook 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`:
|
||||
|
||||
|
||||
|
||||
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.
|
||||
7. When the workflow has finished, visit your build book at `https://<username or organisation_name>.github.io/<repository_name>` (case sensitive). If you added it to the [TUDelft-books GitHub Organization](https://github.com/TUDelft-books) in step 2 it's on `https://oit.tudelft.nl/<repository_name>'. For our example it is [https://dummydocent.github.io/test_book_from_template/](https://dummydocent.github.io/test_book_from_template/) for the TeachBooks template repository and it's [https://oit.tudelft.nl/TUDelft-template/](https://oit.tudelft.nl/TUDelft-template/) for the TU Delft specific version of it. These links are visible in the action's summary as well, as shown in the figure of step 4.
|
||||
|
||||
8. Want to get started directly? Your book contains a few exercises to get your started! Visit `https://<username or organiszation_name>.github.io/<repository_name>/exercises/exercises` (case sensitive) to get started with the first ones to get the basics of how to interact with your book on GitHub.
|
||||
8. Want to get started directly? Your book contains a few exercises to get your started! Visit `https://<username or organiszation_name>.github.io/<repository_name>/exercises/exercises` or `https://oit.tudelft.nl/<repository_name>/exercises/exercises' (case sensitive) to get started with the first ones to get the basics of how to interact with your book on GitHub.
|
||||
|
||||
|
||||
|
||||
|
|
@ -45,7 +47,7 @@ Set the repository website as your GitHub Pages website under `Code`- `About` -
|
|||
|
||||
## 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`)
|
||||
- An empty open interactive textbook 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`)
|
||||
|
|
@ -53,9 +55,9 @@ Set the repository website as your GitHub Pages website under `Code`- `About` -
|
|||
- 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`)
|
||||
- Our [GitHub workflow for publishing your open interactive textbook 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`)
|
||||
|
||||
## 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.io/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 [GitHub repository of the manual](https://github.com/TeachBooks/manual). If you intent to clone the manual including its submodules, clone using: `git clone --recurse-submodulesgit@github.com:TeachBooks/manual.git`.
|
||||
This tool's repository is stored on [GitHub](https://github.com/TeachBooks/template). The [TU-Delft specific version of it](https://github.com/TUDelft-books/TUDelft-template) is a fork of it within the [TUDelft-books GitHub Organization](https://github.com/TUDelft-books). The `README.md` of the branch `manual_description` is also part of the [TeachBooks manual](https://teachbooks.io/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) or the [TU-Delft specific repository](https://github.com/TUDelft-books/TUDelft-template) . To update the `README.md` shown in the TeachBooks manual, create a fork and open a merge request for the [GitHub repository of the manual](https://github.com/TeachBooks/manual). If you intent to clone the manual including its submodules, clone using: `git clone --recurse-submodulesgit@github.com:TeachBooks/manual.git`.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
Title: TeachBooks template
|
||||
author: TeachBooks Team, built with <a href="https://teachbooks.io">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
|
||||
Title: TU Delft OIT GitHub Template
|
||||
author: Author from Delft University of Technology, built with <a href="https://teachbooks.io">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
|
||||
|
||||
execute:
|
||||
execute_notebooks: "off"
|
||||
|
|
@ -8,7 +8,7 @@ only_build_toc_files: true
|
|||
|
||||
html:
|
||||
favicon : "figures/TB_favicon.ico"
|
||||
baseurl : "https://teachbooks.io/" #Replace this with your own URL
|
||||
baseurl : "https://oit.tudelft.nl/" #Replace this with your own URL
|
||||
|
||||
sphinx:
|
||||
config:
|
||||
|
|
@ -19,10 +19,8 @@ sphinx:
|
|||
exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"]
|
||||
html_theme_options:
|
||||
logo:
|
||||
text: Template
|
||||
image_light: TeachBooks_logo.svg # Put your logo for the light mode here (can be the same as image_dark)
|
||||
image_dark: TeachBooks_logo_inverted.svg # Put your logo for the dark mode here (can be the same as image_light)
|
||||
repository_url: "https://github.com/user/repo" #add your own repo URL here
|
||||
text: TU Delft GitHub OIT Template
|
||||
repository_url: "https://github.com/TUDelft-books/repo" #add your own repo URL here
|
||||
path_to_docs: "book"
|
||||
repository_branch: "main"
|
||||
use_edit_page_button: true
|
||||
|
|
@ -43,6 +41,8 @@ sphinx:
|
|||
- download_link_replacer
|
||||
- sphinx.ext.extlinks
|
||||
- sphinx_image_inverter
|
||||
- sphinx_exercise
|
||||
- sphinx_tudelft_theme
|
||||
|
||||
bibtex_bibfiles:
|
||||
- references.bib
|
||||
|
|
|
|||
|
|
@ -3,11 +3,11 @@
|
|||
|
||||
You can refer to this book as:
|
||||
|
||||
> `<editors>` (`<year>`) _`<title>`_. `<url to book website>`. Source files at `<link to github repo`
|
||||
> `<editors>` from Delft University of Technology (`<year>`) _`<title>`_. `<url to book website>`. Source files at `<link to github repo`
|
||||
|
||||
You can refer to individual chapters or pages within this book as:
|
||||
|
||||
> `<Title of Chapter or Page>`. In `<editors>` (`<year>`) _`<title>`_. `<url to specific page on bbook website>`. Source files at `<link to specific commit / file in github repo`
|
||||
> `<Title of Chapter or Page>`. In `<editors>` from Delft University of Technology (`<year>`) _`<title>`_. `<url to specific page on bbook website>`. Source files at `<link to specific commit / file in 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/commit within the book.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Exercises
|
||||
|
||||
> This page reuses CC BY 4.0 licensed content from {cite:t}`template`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
|
||||
|
||||
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. 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}
|
||||
|
|
|
|||
|
|
@ -1,10 +1,12 @@
|
|||
# Exercise 1: First file edit
|
||||
|
||||
> This page reuses CC BY 4.0 licensed content from {cite:t}`template`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
|
||||
|
||||
Let's start with the most basic edit: add some text to a file and see that the website is updated.
|
||||
|
||||
> Can you add some content to the intro page?
|
||||
|
||||
1. Go to the the file `book/intro.md` on your GitHub repository (`https://github.com/<your_username>/<your_repo_name>`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file`
|
||||
1. Go to the the file `book/intro.md` on your GitHub repository (`https://github.com/<your_username>/<your_repo_name>` or `https://github.com/TUDelft-books/<your_repo_name>`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file`
|
||||
2. Add some text. Feeling brave? Have a look at the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html). Don't worry if that feels daunting, there will be exercises on this!
|
||||
3. Click `Commit changes`
|
||||
4. Add a message and description of your change. With this `commit` you save your changes to the git-timeline. Any commit can always be reverted. Therefore, it's useful to shortly explain what is included in your commit. Later on, you'll make commits which may contain changes to many different files. In that case, a descriptive commit message and description is even more useful!
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Exercise 2: Add a new file to the table of contents
|
||||
|
||||
> This page reuses CC BY 4.0 licensed content from {cite:t}`template`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
|
||||
|
||||
Let's continue by adding one additional step. Let's add a file to the table of contents! the `_toc.yml` contains a list of all the files to be shown in your book-website. Let's add a file which is not in the table of contents yet!
|
||||
|
||||
> Can you add the file named `file_to_be_added_to_toc.md` to the book website?
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Exercise 3: Change book configuration
|
||||
|
||||
> This page reuses CC BY 4.0 licensed content from {cite:t}`template`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
|
||||
|
||||
As we've added some content by now, let's make this book a bit more personal! We'll make some changes to the `_config.yml` file which changes the configuration of the book website.
|
||||
|
||||
> 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?
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Exercise 4: _Your_ Version of the Book
|
||||
|
||||
> This page reuses CC BY 4.0 licensed content from {cite:t}`template`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
|
||||
|
||||
By now, we've covered the essentials: content files, `_toc.yml` and `_config.yml`. But what if you want to make some changes but don't want to share them directly with the general public of your book website? Or what if you have some work-in-progress that you want to share with colleagues? You need a version of your book! Let's try and do that! Later on, you'll probably want to merge your newest version back into the original book. That's what we'll do in [](./005.md).
|
||||
|
||||
> Can you make a new branch of your book with an additional file `file_on_new_version.md` and view it online?
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Exercise 5: Merge your version in the original book
|
||||
|
||||
> This page reuses CC BY 4.0 licensed content from {cite:t}`template`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
|
||||
|
||||
In [](./004.md) you created your own version of a book. But it would be a pity if you never contribute back to the original book right? Probably your additions are very useful there too! You'll merge you version of the book which is stored on a branch into the original book which is on main. If there've been some changes on that main branch in the meantime, git will take care of that!
|
||||
|
||||
> Can you merge your branch into `main` with a pull request?
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Exercise 6: Contribute to the book of somebody else
|
||||
|
||||
> This page reuses CC BY 4.0 licensed content from {cite:t}`template`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
|
||||
|
||||
```{tip}
|
||||
For this exercise you will need a partner, as well as your own book. In the first part, each of you will make a change in the book of the other, then request the other to review and merge the change. In the second part, you will go back to your book and accept the change made by your partner.
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Summary of exercises: All Exercises
|
||||
|
||||
> This page reuses CC BY 4.0 licensed content from {cite:t}`template`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
|
||||
|
||||
With the exercises, you did all the steps of our TeachBooks workflow!
|
||||
|
||||
```{figure} ../figures/TeachBooks_flowchart.svg
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 105 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 158 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 368 KiB |
|
|
@ -3,4 +3,12 @@
|
|||
author={Moore, Jason},
|
||||
howpublished={\url{https://moorepants.github.io/learn-multibody-dynamics/sympy.html}},
|
||||
year={2023}
|
||||
}
|
||||
|
||||
@misc{template,
|
||||
author = {{TeachBooks}},
|
||||
title = {Your first TeachBook using the GitHub template},
|
||||
url = {https://github.com/TeachBooks/template},
|
||||
year = {2024},
|
||||
note = {Retrieved December, 2024. CC BY 4.0.}
|
||||
}
|
||||
|
|
@ -3,6 +3,8 @@ teachbooks # depends on jupyter-book
|
|||
jupyterbook-patches
|
||||
sphinx-image-inverter
|
||||
download_link_replacer
|
||||
sphinx-tudelft-theme
|
||||
sphinx-exercise
|
||||
|
||||
# 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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue