From f09b2d7fa39899a148886aa66ee2a1ea0a164645 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 28 Oct 2024 09:23:38 +0100 Subject: [PATCH 01/38] Updated editing team and tools --- book/installation-and-setup/organize-team.md | 22 ++++++++++---------- book/workflows/permissions.md | 1 - 2 files changed, 11 insertions(+), 12 deletions(-) delete mode 100644 book/workflows/permissions.md diff --git a/book/installation-and-setup/organize-team.md b/book/installation-and-setup/organize-team.md index 4da66bc..18ccbc0 100644 --- a/book/installation-and-setup/organize-team.md +++ b/book/installation-and-setup/organize-team.md @@ -23,23 +23,23 @@ If you want to create a collaborative book for students, there's a few agreement - Choose whether to have your git repository public or private (independent of whether your book website is public or private). If you'd like a private repo on GitHub, apply for a GitHub Team (free as a teacher as described in the [github documentation](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers)). If you've a organization for your book on github, link your GitHub team rights to your organization as described on the [github website](https://github.com/team#organizations) - If you've chosen for GitHub, start with our [template](../external/template/README.md) - Define branches in GitHub/GitLab. We advise the following branches: - - A published branch which contains the students' version of this year. This could be called ie. `publish` or `main` or ``. Add this branch as the `PRIMARY BRANCH` when making use of the [github workflow](gh-workflow-settings), this will make sure students are redirected to this URL which doesn't move when adding new versions of the book later on. If you plan on keeping only one public version, it's advised to set `BEHAVIOR_PRIMARY` from the default `redirect` to `copy` which makes sure the primary branch is copied to root so that the URL is compact. + - A release branch which contains the students' version of this year. This could be called ie. `release` or `main` or ``. Add this branch as the `PRIMARY BRANCH` when making use of the [github workflow](gh-workflow-settings), this will make sure students are redirected to this URL which doesn't move when adding new versions of the book later on. If you plan on keeping only one public version, it's advised to set `BEHAVIOR_PRIMARY` from the default `redirect` to `copy` which makes sure the primary branch is copied to root so that the URL is compact. - A development branch which contains all the new content combined but not yet published to students. This could be called ie. `dev` or `main`. `dev` is advised when you prefer git's default branch to be the most recent published version (as `main` is expected to be the default branch by many). - Branches which will be created during the editing process, which is probably something which you want to allow. As long as `BRANCHES_TO_DEPLOY` is set to the default `*`, all branches are build and your fellow editors can review their own and each other's versions online. Once every while, it doesn't hurt to go through the list of branches and delete any branches which are merged but not deleted. - - (future) branches for previous study years which contain each year's version of the book. These could be called `` which ends up in their url too. Add these branches to the list of `BRANCHES_ARCHIVED` when making use of the [github workflow](gh-workflow-settings) to add a banner to the page indicating it's archived state. + - Branches for previous study years which contain each year's version of the book. These could be called `` which ends up in their url too. Add these branches to the list of `BRANCHES_ARCHIVED` when making use of the [github workflow](gh-workflow-settings) to add a banner to the page indicating it's archived state. - Setup protected branches in GitHub/GitLab to prevent accidental changes - Add people with GitHub/GitLab permission matching their role and the protected branches. - Add a readme explaining the way you organized branches and permissions - Provide explanation on how you'd like to receive feedback in both the readme as the published book. The use of issues (in the book with the issue button) is advised. -- Decide on whether or not to publish your book via Open Interactive Textbooks TU Delft. Publishing will give you a copyright check, ISBN and DOI number but heavily limits the amount of changes you can make to your book. We advise publishing an archived version of your book whenever the academic year is over. +- Decide on whether or not to publish your book via Open Interactive Textbooks TU Delft. Publishing will give you a copyright check, ISBN, DOI number, and registration in several shared databases but heavily limits the amount of changes you can make to your book. In case of editing a book for a course during that actual course, we advise publishing an archived version of your book whenever the academic year is over. ### GitHub vs GitLab -- Github allows you to host your book on the GitHub server using GitHub pages (to be recognized by the `.github.io/` url, for example the [template book](https://teachbooks.github.io/template/)), which takes all the steps of hosting out of your hands. You can also use a custom owned URL, although this requires some additional skills. On TU Delft's GitLab you need a webserver, which is offered by TeachBooks (to be recognized by the url `teachbooks.tudelft.nl/`, for example [this manual](https://teachbooks.tudelft.nl/jupyter-book-manual)) as the TU Delft OIT team (to be recognized by the url `interactivetextbooks.tudelft.nl/`, for example [the TU Delft OIT demo book](https://interactivetextbooks.tudelft.nl/open-textbooks-demonstration/)). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in the editing-phase. +- Github allows you to host your book on the GitHub server using GitHub pages (to be recognized by the `.github.io/` url, for example the [template book](https://teachbooks.github.io/template/)), which takes all the steps of hosting out of your hands. You can also use a custom owned URL, although this requires some additional skills. On TU Delft's GitLab you need a webserver, which is offered by TeachBooks (to be recognized by the url `teachbooks.tudelft.nl/`, for example [this manual](https://teachbooks.tudelft.nl/jupyter-book-manual)) as the TU Delft OIT team (to be recognized by the url `interactivetextbooks.tudelft.nl/`, for example [the TU Delft OIT demo book](https://interactivetextbooks.tudelft.nl/open-textbooks-demonstration/)). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in an active editing-phase. - 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 GitHub we developed a [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). On GitLab both we and other people at TU Delft have a more simplistic workflow which can be used when you're set up on those Git environments and webservers. If you want to use GitLab and make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github) -- Because we’re in control on the server connected to GitLab, we can set up SSO login for visitors of the website. This is not an option for GitHub because we don’t own the server. -- Both GitLab and GitHub allow for extensive options for visibility of the source code. If you're using GitHub pages, you need a free organization linked to a free eduational account. The TU Delft GitLab requires SSO login for editing the book. Although this is useful for TU Delft employees, it limits the collaboration with people outside of TU Delft. +- On GitHub we developed a [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). On GitLab both we and other people at TU Delft have a more simplistic workflow which can be used when you're set up on those Git environments and webservers. If you want to use GitLab but still want to make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github) +- When you’re publishing 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. If you want the same functionality with GitHub pages, your book should be part of the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft). This SSO login is a bit different as you're required to give access to specific accounts. Furthermore, the url of you're book on GitHub pages is a random one, so you might consider using a custom URL. +- Both GitLab and GitHub allow for extensive options for visibility of the source code. The TU Delft GitLab requires SSO login for editing the book. Although this is useful for TU Delft employees, it limits the collaboration with people outside of TU Delft. - GitHub has a nice integration with the [GitHub Desktop application](git-setup_local.md). For GitLab it works as well, but has less functionality. - [Utteranc.es](../basic-features/utterances.md) requires a GitHub repository to host the discussions. If you're using a GitLab repository, you need a separate GitHub repository and the discussions and book content is not at the same place. @@ -48,10 +48,10 @@ If you have doubt about this choice, we advise you to start on GitHub. Moving/du Here's a table summarizing the information: | | GitHub | GitLab | |--|----------|-------------| -| Website to view book online | GitHub pages (`.github.io/`) or custom URL 🌐 | TeachBooks (`teachbooks.tudelft.nl/`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/`) 🎓 | -| Setting up book website | Immediate and automated with [template](../external/template/README.md) ⚡️ | Access required by TeachBooks or TU Delft OIT 🚧 | +| Website to view book online | GitHub pages (`.github.io/`), for TU Delft GitHub Enterprise with SSO a random URL (`.github.io/`), or custom url `./`> 🌐 | TeachBooks (`teachbooks.tudelft.nl/`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/`) 🎓 | +| Setting up book website | Immediate and automated with [template](../external/template/README.md) ⚡️ | Manual setup on personal webserver, or access required by TeachBooks or TU Delft OIT 🚧 | | Updating book website | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) 🚀 | Automated but simplistic (one or two versions, command-line interface) 🛵 | -| Student book access with SSO | Not available for GitHub pages ❌, optional with custom URL ✅ | Optional ✅ | -| Teacher/TA access to Git repository | Private (if part of organization linked to educational account) /public 👀 | Private / public / internally TU Delft, editing requires requires SSO login 👥 | +| Student book access with SSO | Only available for GitHub pages on GitHub Enterprise of TU Delft ❌, optional with custom URL ✅ | Optional ✅ | +| Access to source code | Private (if part of organization linked to educational account) /public / internally TU Delft (on GitHub Enterprise of TU Delft) 👥 | Private / public (read-only) / internally TU Delft, editing requires requires SSO login 👥 👀 | | GitHub Desktop | Well integrated 😎 | Basic integration 🙂 | | Utteranc.es | Can be linked to same repository 🏷️ | Requires GitHub repository next to GitLab repository 🏷️🏷️| \ No newline at end of file diff --git a/book/workflows/permissions.md b/book/workflows/permissions.md deleted file mode 100644 index 2aef880..0000000 --- a/book/workflows/permissions.md +++ /dev/null @@ -1 +0,0 @@ -# Access Control / Permissions \ No newline at end of file From cfdd56d035db7dd918e15c55dc5df69c0b853809 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 28 Oct 2024 09:40:41 +0100 Subject: [PATCH 02/38] Update organize-team.md --- book/installation-and-setup/organize-team.md | 55 ++++++++++++++------ 1 file changed, 40 insertions(+), 15 deletions(-) diff --git a/book/installation-and-setup/organize-team.md b/book/installation-and-setup/organize-team.md index 18ccbc0..c7e8ea1 100644 --- a/book/installation-and-setup/organize-team.md +++ b/book/installation-and-setup/organize-team.md @@ -7,14 +7,12 @@ This page is useful for user type 4-5. If you want to create a collaborative book for students, there's a few agreements you should make to enhance collaboration and student experience. These are written from our own experience, feel free to deviate or provide your own advice! -**This page is work in progress** - ## Team - Define who's in charge of: - Team organization (administrators), at least user type 4 - Combining content (maintainers), at least user type 4 - Editing and reviewing content (editors) -- Define how your review process is taking place. We advice at least a maintainer reviewing each bit o content. +- Define how your review process is taking place. We advice at least a maintainer reviewing each bit of content. - Make sure people identify themselves as one of the user types. You should have at least one user type 4 or 5. Although this can be a TA, it is advised one of the teachers is comfortable with this user type as well. ## Tools @@ -35,23 +33,50 @@ If you want to create a collaborative book for students, there's a few agreement ### GitHub vs GitLab -- Github allows you to host your book on the GitHub server using GitHub pages (to be recognized by the `.github.io/` url, for example the [template book](https://teachbooks.github.io/template/)), which takes all the steps of hosting out of your hands. You can also use a custom owned URL, although this requires some additional skills. On TU Delft's GitLab you need a webserver, which is offered by TeachBooks (to be recognized by the url `teachbooks.tudelft.nl/`, for example [this manual](https://teachbooks.tudelft.nl/jupyter-book-manual)) as the TU Delft OIT team (to be recognized by the url `interactivetextbooks.tudelft.nl/`, for example [the TU Delft OIT demo book](https://interactivetextbooks.tudelft.nl/open-textbooks-demonstration/)). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in an active editing-phase. -- 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 GitHub we developed a [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). On GitLab both we and other people at TU Delft have a more simplistic workflow which can be used when you're set up on those Git environments and webservers. If you want to use GitLab but still want to make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github) -- When you’re publishing 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. If you want the same functionality with GitHub pages, your book should be part of the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft). This SSO login is a bit different as you're required to give access to specific accounts. Furthermore, the url of you're book on GitHub pages is a random one, so you might consider using a custom URL. -- Both GitLab and GitHub allow for extensive options for visibility of the source code. The TU Delft GitLab requires SSO login for editing the book. Although this is useful for TU Delft employees, it limits the collaboration with people outside of TU Delft. -- GitHub has a nice integration with the [GitHub Desktop application](git-setup_local.md). For GitLab it works as well, but has less functionality. -- [Utteranc.es](../basic-features/utterances.md) requires a GitHub repository to host the discussions. If you're using a GitLab repository, you need a separate GitHub repository and the discussions and book content is not at the same place. +#### Book URL +Github allows you to host your book on the GitHub server using GitHub pages (to be recognized by the `.github.io/` url, for example the [template book](https://teachbooks.github.io/template/)), which takes all the steps of hosting out of your hands. If you're book is part of the [GitHub Enterprise TU Delft](https://github.com/enterprises/tudelft) and is using SSO, a random url is generated `.github.io/`. Next to GitHub-provided URLs, you can set up a custom owned URL, although this requires some additional skills on a domain which you should own. -If you have doubt about this choice, we advise you to start on GitHub. Moving/duplicating your content to GitLab or hosting to a custom URL is always possible at a later stage. +On TU Delft's GitLab you need a webserver, which is offered by TeachBooks (to be recognized by the url `teachbooks.tudelft.nl/`, for example [this manual](https://teachbooks.tudelft.nl/jupyter-book-manual)) as the TU Delft OIT team (to be recognized by the url `interactivetextbooks.tudelft.nl/`, for example [the TU Delft OIT demo book](https://interactivetextbooks.tudelft.nl/open-textbooks-demonstration/)). +#### Real-time editing book +Editing the book can happen both locally as online on GitHub/GitLab. If done locally, the book can be generated and viewed locally too (typically takes around 1 minute) but this requires you to be at least user type 4 or 5 depending on the book content. The built book can also be viewed online separate from the released version. + +On GitHub we developed a [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). + +On GitLab both we and other people at TU Delft have a more simplistic workflow which can be used when you're set up on those Git environments and webservers. If you want to use GitLab but still want to make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in an active editing-phase since constant copyright checks have to be performed. + +#### 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. + +#### 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. + +If you want the same functionality with GitHub pages, your book should be part of the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft). This SSO login is a bit different as you're required to give access to specific accounts. Furthermore, the url of you're book on GitHub pages is a random one, so you might consider using a custom URL. + +#### Access to source code + +Both GitLab and GitHub allow for extensive options for visibility of the source code, both private, public or internally. On GitHub, public allows for collaboration with anyone. For SSO login, your book should be part of the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft) + +The TU Delft GitLab requires SSO login for editing the book. Although this is useful for TU Delft employees, it limits the collaboration with people outside of TU Delft. + +#### Integration with GitHub Desktop +GitHub has a nice integration with the [GitHub Desktop application](git-setup_local.md). For GitLab it works as well, but has less functionality. + +#### Intergration with Utteranc.es +[Utteranc.es](../basic-features/utterances.md) requires a GitHub repository to host the discussions. If you're using a GitLab repository, you need a separate GitHub repository and the discussions and book content is not at the same place. + +#### Summary Here's a table summarizing the information: | | GitHub | GitLab | |--|----------|-------------| -| Website to view book online | GitHub pages (`.github.io/`), for TU Delft GitHub Enterprise with SSO a random URL (`.github.io/`), or custom url `./`> 🌐 | TeachBooks (`teachbooks.tudelft.nl/`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/`) 🎓 | +| Book url | GitHub pages (`.github.io/`), for TU Delft GitHub Enterprise with SSO a random URL (`.github.io/`), or custom url `./`> 🌐 | TeachBooks (`teachbooks.tudelft.nl/`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/`) 🎓 | +| Real-time book editing | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) 🚀 | Automated but simplistic (one or two versions, command-line interface) 🛵 For TU Delft OIT: restricted adaptations because of copyright checks 🚫 | | Setting up book website | Immediate and automated with [template](../external/template/README.md) ⚡️ | Manual setup on personal webserver, or access required by TeachBooks or TU Delft OIT 🚧 | -| Updating book website | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) 🚀 | Automated but simplistic (one or two versions, command-line interface) 🛵 | -| Student book access with SSO | Only available for GitHub pages on GitHub Enterprise of TU Delft ❌, optional with custom URL ✅ | Optional ✅ | +| Book access with SSO | Only available for GitHub pages on GitHub Enterprise of TU Delft ❌, optional with custom URL ✅ | Optional ✅ | | Access to source code | Private (if part of organization linked to educational account) /public / internally TU Delft (on GitHub Enterprise of TU Delft) 👥 | Private / public (read-only) / internally TU Delft, editing requires requires SSO login 👥 👀 | | GitHub Desktop | Well integrated 😎 | Basic integration 🙂 | -| Utteranc.es | Can be linked to same repository 🏷️ | Requires GitHub repository next to GitLab repository 🏷️🏷️| \ No newline at end of file +| Utteranc.es | Can be linked to same repository 🏷️ | Requires GitHub repository next to GitLab repository 🏷️🏷️| + +If you have doubt about this choice, we advise you to start on GitHub. Moving/duplicating your content to GitLab or hosting to a custom URL is always possible at a later stage. \ No newline at end of file From 475c3204f54b0315ff015d6ac4a3cba90e76e1bc Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 28 Oct 2024 10:09:31 +0100 Subject: [PATCH 03/38] splitted organize team and extended collab --- book/_toc.yml | 3 + book/installation-and-setup/collab.md | 17 +++++ book/installation-and-setup/organize-team.md | 76 +------------------ book/installation-and-setup/tools.md | 77 ++++++++++++++++++++ 4 files changed, 98 insertions(+), 75 deletions(-) create mode 100644 book/installation-and-setup/collab.md create mode 100644 book/installation-and-setup/tools.md diff --git a/book/_toc.yml b/book/_toc.yml index 16d456e..a2c7ed8 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -22,6 +22,9 @@ parts: - file: workflows/check_changes_online - file: workflows/merge_request - file: installation-and-setup/organize-team + sections: + - file: installation-and-setup/collab + - file: installation-and-setup/tools - file: installation-and-setup/creating_content.md - caption: Features chapters: diff --git a/book/installation-and-setup/collab.md b/book/installation-and-setup/collab.md new file mode 100644 index 0000000..3a983fd --- /dev/null +++ b/book/installation-and-setup/collab.md @@ -0,0 +1,17 @@ +# Team and collaboration + +## Roles and responsibilities +To ensure smooth collaboration, it is essential to define the roles and responsibilities within your team. Firstly, designate who will be in charge of team organization ('administrators') who should be at least user type 4. Additionally, assign 'maintainers' responsible for combining content, also requiring at least user type 4. 'Editors' should be identified for editing and reviewing content, requiring at least user type 3. + +Finally, ensure that team members identify themselves according to the user types. It is crucial to have at least one user type 4 or 5 on the team. While this role can be filled by a teaching assistant (TA), it is recommended that one of the teachers is also comfortable with this user type to provide adequate support and oversight. + +## Review process +Furthermore, establish a clear editing and review process. + +For the editing process, establish some practical rules on whether to use issues, branches and forks for adding content, fixing typos or making other changes. Furthermore, it can help to write down when you expect (draft) merge/pull requests and how to use the assign and review options in GitHub/GitLab. It is advisable to have at least a maintainer review each piece of content to maintain quality and consistency. + +## Private, internally or public +Choose whether you want to share your source code and built book privately, internally or publicly. In any case, you need to obey copyright-rules. We advise public repositories and books in line with a vision on open education. + +## Publishing via Open Interactive Textbooks TU Delft +Decide on whether or not to publish your book via Open Interactive Textbooks TU Delft. Publishing will give you a copyright check, ISBN, DOI number, and registration in several shared databases but heavily limits the amount of changes you can make to your book. In case of editing a book for a course during that actual course and if your book is worth publishing outside of your course's content, we advise only publishing an archived version of your book whenever the academic year is over. \ No newline at end of file diff --git a/book/installation-and-setup/organize-team.md b/book/installation-and-setup/organize-team.md index c7e8ea1..3c4f7b0 100644 --- a/book/installation-and-setup/organize-team.md +++ b/book/installation-and-setup/organize-team.md @@ -5,78 +5,4 @@ This page is useful for user type 4-5. ``` -If you want to create a collaborative book for students, there's a few agreements you should make to enhance collaboration and student experience. These are written from our own experience, feel free to deviate or provide your own advice! - -## Team -- Define who's in charge of: - - Team organization (administrators), at least user type 4 - - Combining content (maintainers), at least user type 4 - - Editing and reviewing content (editors) -- Define how your review process is taking place. We advice at least a maintainer reviewing each bit of content. -- Make sure people identify themselves as one of the user types. You should have at least one user type 4 or 5. Although this can be a TA, it is advised one of the teachers is comfortable with this user type as well. - -## Tools -- Choose between GitHub and GitLab, as explained below -- Choose whether to host your git repository in your private account or from a share teams (groups in GitLab, organization in GitHub). For GitHub this influences your book web url as well, as it hold your username or organization name. For courses we therefore advise you to create a organization with the course name. Furthermore, on GitHub a private repository has a limited amount of actions-minutes required for published your book. On GitLab, the choice for private or public doesn't influence your web url and the amount of computing power available as that requires you to set up a server yourself. -- Choose whether to have your git repository public or private (independent of whether your book website is public or private). If you'd like a private repo on GitHub, apply for a GitHub Team (free as a teacher as described in the [github documentation](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers)). If you've a organization for your book on github, link your GitHub team rights to your organization as described on the [github website](https://github.com/team#organizations) -- If you've chosen for GitHub, start with our [template](../external/template/README.md) -- Define branches in GitHub/GitLab. We advise the following branches: - - A release branch which contains the students' version of this year. This could be called ie. `release` or `main` or ``. Add this branch as the `PRIMARY BRANCH` when making use of the [github workflow](gh-workflow-settings), this will make sure students are redirected to this URL which doesn't move when adding new versions of the book later on. If you plan on keeping only one public version, it's advised to set `BEHAVIOR_PRIMARY` from the default `redirect` to `copy` which makes sure the primary branch is copied to root so that the URL is compact. - - A development branch which contains all the new content combined but not yet published to students. This could be called ie. `dev` or `main`. `dev` is advised when you prefer git's default branch to be the most recent published version (as `main` is expected to be the default branch by many). - - Branches which will be created during the editing process, which is probably something which you want to allow. As long as `BRANCHES_TO_DEPLOY` is set to the default `*`, all branches are build and your fellow editors can review their own and each other's versions online. Once every while, it doesn't hurt to go through the list of branches and delete any branches which are merged but not deleted. - - Branches for previous study years which contain each year's version of the book. These could be called `` which ends up in their url too. Add these branches to the list of `BRANCHES_ARCHIVED` when making use of the [github workflow](gh-workflow-settings) to add a banner to the page indicating it's archived state. -- Setup protected branches in GitHub/GitLab to prevent accidental changes -- Add people with GitHub/GitLab permission matching their role and the protected branches. -- Add a readme explaining the way you organized branches and permissions -- Provide explanation on how you'd like to receive feedback in both the readme as the published book. The use of issues (in the book with the issue button) is advised. -- Decide on whether or not to publish your book via Open Interactive Textbooks TU Delft. Publishing will give you a copyright check, ISBN, DOI number, and registration in several shared databases but heavily limits the amount of changes you can make to your book. In case of editing a book for a course during that actual course, we advise publishing an archived version of your book whenever the academic year is over. - -### GitHub vs GitLab - -#### Book URL -Github allows you to host your book on the GitHub server using GitHub pages (to be recognized by the `.github.io/` url, for example the [template book](https://teachbooks.github.io/template/)), which takes all the steps of hosting out of your hands. If you're book is part of the [GitHub Enterprise TU Delft](https://github.com/enterprises/tudelft) and is using SSO, a random url is generated `.github.io/`. Next to GitHub-provided URLs, you can set up a custom owned URL, although this requires some additional skills on a domain which you should own. - -On TU Delft's GitLab you need a webserver, which is offered by TeachBooks (to be recognized by the url `teachbooks.tudelft.nl/`, for example [this manual](https://teachbooks.tudelft.nl/jupyter-book-manual)) as the TU Delft OIT team (to be recognized by the url `interactivetextbooks.tudelft.nl/`, for example [the TU Delft OIT demo book](https://interactivetextbooks.tudelft.nl/open-textbooks-demonstration/)). - -#### Real-time editing book -Editing the book can happen both locally as online on GitHub/GitLab. If done locally, the book can be generated and viewed locally too (typically takes around 1 minute) but this requires you to be at least user type 4 or 5 depending on the book content. The built book can also be viewed online separate from the released version. - -On GitHub we developed a [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). - -On GitLab both we and other people at TU Delft have a more simplistic workflow which can be used when you're set up on those Git environments and webservers. If you want to use GitLab but still want to make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in an active editing-phase since constant copyright checks have to be performed. - -#### 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. - -#### 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. - -If you want the same functionality with GitHub pages, your book should be part of the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft). This SSO login is a bit different as you're required to give access to specific accounts. Furthermore, the url of you're book on GitHub pages is a random one, so you might consider using a custom URL. - -#### Access to source code - -Both GitLab and GitHub allow for extensive options for visibility of the source code, both private, public or internally. On GitHub, public allows for collaboration with anyone. For SSO login, your book should be part of the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft) - -The TU Delft GitLab requires SSO login for editing the book. Although this is useful for TU Delft employees, it limits the collaboration with people outside of TU Delft. - -#### Integration with GitHub Desktop -GitHub has a nice integration with the [GitHub Desktop application](git-setup_local.md). For GitLab it works as well, but has less functionality. - -#### Intergration with Utteranc.es -[Utteranc.es](../basic-features/utterances.md) requires a GitHub repository to host the discussions. If you're using a GitLab repository, you need a separate GitHub repository and the discussions and book content is not at the same place. - -#### Summary -Here's a table summarizing the information: -| | GitHub | GitLab | -|--|----------|-------------| -| Book url | GitHub pages (`.github.io/`), for TU Delft GitHub Enterprise with SSO a random URL (`.github.io/`), or custom url `./`> 🌐 | TeachBooks (`teachbooks.tudelft.nl/`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/`) 🎓 | -| Real-time book editing | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) 🚀 | Automated but simplistic (one or two versions, command-line interface) 🛵 For TU Delft OIT: restricted adaptations because of copyright checks 🚫 | -| Setting up book website | Immediate and automated with [template](../external/template/README.md) ⚡️ | Manual setup on personal webserver, or access required by TeachBooks or TU Delft OIT 🚧 | -| Book access with SSO | Only available for GitHub pages on GitHub Enterprise of TU Delft ❌, optional with custom URL ✅ | Optional ✅ | -| Access to source code | Private (if part of organization linked to educational account) /public / internally TU Delft (on GitHub Enterprise of TU Delft) 👥 | Private / public (read-only) / internally TU Delft, editing requires requires SSO login 👥 👀 | -| GitHub Desktop | Well integrated 😎 | Basic integration 🙂 | -| Utteranc.es | Can be linked to same repository 🏷️ | Requires GitHub repository next to GitLab repository 🏷️🏷️| - -If you have doubt about this choice, we advise you to start on GitHub. Moving/duplicating your content to GitLab or hosting to a custom URL is always possible at a later stage. \ No newline at end of file +If you want to create a collaborative book for students, there's a few agreements you should make to enhance collaboration and student experience. These are written from our own experience, feel free to deviate or provide your own advice! A distinction has been made between organization of teams and tools. \ No newline at end of file diff --git a/book/installation-and-setup/tools.md b/book/installation-and-setup/tools.md new file mode 100644 index 0000000..bb7c666 --- /dev/null +++ b/book/installation-and-setup/tools.md @@ -0,0 +1,77 @@ +# Tools +The setup of tools is dependent on agreement you've made. + +## Collaboration in readme +Provide explanation on how you organize the book-editing and how you'd like to receive feedback in both the readme as the published book. The use of the [issue button](https://jupyterbook.org/en/stable/basics/repository.html#add-a-button-to-open-issues) is advised for the published book. + +## Branches for separate versions +We recommend using at least two separate branches, one which is released to students, the other on for development. If you're planning adapting the book every year, you should set up your branches in such a way that students will always receive the version they should expect. + +Firstly, create a release branch which contains the students' version of this year. This branch could be named `release`, `main`, or ``. It is recommended to set this branch as the `PRIMARY BRANCH` when using the [GitHub workflow](gh-workflow-settings). This ensures that students are redirected to a consistent URL, even when new versions of the book are added later. If you plan on maintaining only one public version, it is advisable to set `BEHAVIOR_PRIMARY` from the default `redirect` to `copy`. This ensures that the primary branch is copied to the root, making the URL more compact. + +Next, establish a development branch that contains all the new content combined but not yet published to students. This branch could be named `dev` or `main`. Using `dev` is recommended if you prefer the default branch to be the most recent published version, as `main` is commonly expected to be the default branch. + +Additionally, allow the creation of branches during the editing process. As long as `BRANCHES_TO_DEPLOY` is set to the default `*`, all branches will be built, enabling fellow editors to review their own and each other's versions online. Periodically, it is beneficial to review the list of branches and delete any that have been merged but not deleted. + +Eventually, create branches for previous study years, each containing that year's version of the book. These branches could be named ``, which will also be reflected in their URLs. Add these branches to the list of `BRANCHES_ARCHIVED` when using the [GitHub workflow](gh-workflow-settings) to include a banner on the page indicating its archived state. + +Lastly, add a readme explaining the way you organized branches. + +## Protect branches + +To ensure the integrity of your book's content, it is crucial to set up protected branches in both GitHub and GitLab. Protected branches prevent accidental changes and ensure that only authorized modifications are made. In GitHub, you can configure branch protection rules by navigating to the repository settings, selecting "Branches," and then adding branch protection rules for the branches you want to protect. Similarly, in GitLab, you can protect branches by going to the repository settings, selecting "Repository," and then configuring the branch protection settings. + +Once the branches are protected, it is essential to assign appropriate permissions to team members based on their roles. In GitHub, you can manage permissions by navigating to the repository settings, selecting "Manage access," and then inviting collaborators with specific roles such as "Admin," "Write," or "Read." In GitLab, permissions can be managed by going to the project settings, selecting "Members," and then adding users with roles like "Maintainer," "Developer," or "Reporter." + +Additionally, it is advisable to document the branch protection strategy and the assigned permissions in the readme file. This documentation should explain the rationale behind the branch protection rules and provide clear instructions on how team members can request access or permission changes. By doing so, you create a transparent and organized workflow that facilitates collaboration and minimizes the risk of unauthorized changes. + +## GitHub vs GitLab +Choosing between GitHub and GitLab depends on multiple criteria. GitHub provides more functionalities, but you might prefer the TU Delft-closed GitLab system. + +### Book URL +Github allows you to host your book on the GitHub server using GitHub pages (to be recognized by the `.github.io/` url, for example the [template book](https://teachbooks.github.io/template/)), which takes all the steps of hosting out of your hands. If you're book is part of the [GitHub Enterprise TU Delft](https://github.com/enterprises/tudelft) and is using SSO, a random url is generated `.github.io/`. Next to GitHub-provided URLs, you can set up a custom owned URL, although this requires some additional skills on a domain which you should own. For courses we advise you to create a organization with the course name so that the URL represent that course. + +On TU Delft's GitLab you need a webserver, which is offered by TeachBooks (to be recognized by the url `teachbooks.tudelft.nl/`, for example [this manual](https://teachbooks.tudelft.nl/jupyter-book-manual)) as the TU Delft OIT team (to be recognized by the url `interactivetextbooks.tudelft.nl/`, for example [the TU Delft OIT demo book](https://interactivetextbooks.tudelft.nl/open-textbooks-demonstration/)). + +### Real-time editing book +Editing the book can happen both locally as online on GitHub/GitLab. If done locally, the book can be generated and viewed locally too (typically takes around 1 minute) but this requires you to be at least user type 4 or 5 depending on the book content. The built book can also be viewed online separate from the released version. + +On GitHub we developed a [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). For a private repository, there is an extensive but limited amount of actions-minutes required for published your book. If this proves to be a limit, consider applying for [Teacher benefits](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers) or joining the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft). + +On GitLab a webserver is required to process book-changes online. Both we and other people at TU Delft have a simplistic workflow which can be used when you're set up on those Git environments and webservers. If you want to use GitLab but still want to make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in an active editing-phase since constant copyright checks have to be performed. The amount of computing power available is dependent on how you set the server yourself. + +### 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. + +### 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. + +If you want the same functionality with GitHub pages, your book should be part of the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft). This SSO login is a bit different as you're required to give access to specific accounts. Furthermore, the url of you're book on GitHub pages is a random one, so you might consider using a custom URL. + +### Access to source code + +Both GitLab and GitHub allow for extensive options for visibility of the source code, both private, public or internally. On GitHub, public allows for collaboration with anyone. For SSO login, your book should be part of the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft). If you'd like a private repo on GitHub, apply for a GitHub Team (free as a teacher as described in the [github documentation](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers)) to make use of GitHub pages (for public repos GitHub pages is not restricted). + +The TU Delft GitLab requires SSO login for editing the book. Although this is useful for TU Delft employees, it limits the collaboration with people outside of TU Delft. + +### Integration with GitHub Desktop +GitHub has a nice integration with the [GitHub Desktop application](git-setup_local.md). For GitLab it works as well, but has less functionality. + +### Intergration with Utteranc.es +[Utteranc.es](../basic-features/utterances.md) requires a GitHub repository to host the discussions. If you're using a GitLab repository, you need a separate GitHub repository and the discussions and book content is not at the same place. + +### Summary +Here's a table summarizing the information: +| | GitHub | GitLab | +|--|----------|-------------| +| Book url | GitHub pages (`.github.io/`), for TU Delft GitHub Enterprise with SSO a random URL (`.github.io/`), or custom url `./`> 🌐 | TeachBooks (`teachbooks.tudelft.nl/`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/`) 🎓 | +| Real-time book editing | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) 🚀 | Automated but simplistic (one or two versions, command-line interface) 🛵 For TU Delft OIT: restricted adaptations because of copyright checks 🚫 | +| Setting up book website | Immediate and automated with [template](../external/template/README.md) ⚡️ | Manual setup on personal webserver, or access required by TeachBooks or TU Delft OIT 🚧 | +| Book access with SSO | Only available for GitHub pages on GitHub Enterprise of TU Delft ❌, optional with custom URL ✅ | Optional ✅ | +| Access to source code | Private (if part of organization linked to educational account) /public / internally TU Delft (on GitHub Enterprise of TU Delft) 👥 | Private / public (read-only) / internally TU Delft, editing requires requires SSO login 👥 👀 | +| GitHub Desktop | Well integrated 😎 | Basic integration 🙂 | +| Utteranc.es | Can be linked to same repository 🏷️ | Requires GitHub repository next to GitLab repository 🏷️🏷️| + +If you have doubt about this choice, we advise you to start on GitHub. Moving/duplicating your content to GitLab or hosting to a custom URL is always possible at a later stage. \ No newline at end of file From 425f3c453156c5011e4c33c09a0a1ecf79bd75e5 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 28 Oct 2024 10:13:30 +0100 Subject: [PATCH 04/38] Update tools.md --- book/installation-and-setup/tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/installation-and-setup/tools.md b/book/installation-and-setup/tools.md index bb7c666..a14ee80 100644 --- a/book/installation-and-setup/tools.md +++ b/book/installation-and-setup/tools.md @@ -1,5 +1,5 @@ # Tools -The setup of tools is dependent on agreement you've made. +The setup of tools is dependent on agreements you've made. ## Collaboration in readme Provide explanation on how you organize the book-editing and how you'd like to receive feedback in both the readme as the published book. The use of the [issue button](https://jupyterbook.org/en/stable/basics/repository.html#add-a-button-to-open-issues) is advised for the published book. From ce1a2a0114995105313e6433f8b05095ee6a9aed Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 28 Oct 2024 10:13:58 +0100 Subject: [PATCH 05/38] Update tools.md --- book/installation-and-setup/tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/installation-and-setup/tools.md b/book/installation-and-setup/tools.md index a14ee80..d88ea71 100644 --- a/book/installation-and-setup/tools.md +++ b/book/installation-and-setup/tools.md @@ -1,5 +1,5 @@ # Tools -The setup of tools is dependent on agreements you've made. +The setup of tools is dependent on agreements you've made on collaboration. ## Collaboration in readme Provide explanation on how you organize the book-editing and how you'd like to receive feedback in both the readme as the published book. The use of the [issue button](https://jupyterbook.org/en/stable/basics/repository.html#add-a-button-to-open-issues) is advised for the published book. From c24bb4d4c0efc038d168326140d6929a31edafc9 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 28 Oct 2024 10:16:21 +0100 Subject: [PATCH 06/38] Update _config.yml --- book/_config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_config.yml b/book/_config.yml index ebffffa..089e0ba 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -1,5 +1,5 @@ title: TeachBooks Manual -author: TeachBooks Team from Delft university of Technology, built with TeachBooks and Jupyter Book, CC BY 4.0 +author: TeachBooks Team from Delft University of Technology, built with TeachBooks and Jupyter Book, CC BY 4.0 logo: images/Logo_without_background.png From 3d96b9fcdc6c536594c7eca07fe6d55beed99095 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 28 Oct 2024 10:19:37 +0100 Subject: [PATCH 07/38] Update tools.md --- book/installation-and-setup/tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/installation-and-setup/tools.md b/book/installation-and-setup/tools.md index d88ea71..a0156cc 100644 --- a/book/installation-and-setup/tools.md +++ b/book/installation-and-setup/tools.md @@ -69,7 +69,7 @@ Here's a table summarizing the information: | Book url | GitHub pages (`.github.io/`), for TU Delft GitHub Enterprise with SSO a random URL (`.github.io/`), or custom url `./`> 🌐 | TeachBooks (`teachbooks.tudelft.nl/`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/`) 🎓 | | Real-time book editing | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) 🚀 | Automated but simplistic (one or two versions, command-line interface) 🛵 For TU Delft OIT: restricted adaptations because of copyright checks 🚫 | | Setting up book website | Immediate and automated with [template](../external/template/README.md) ⚡️ | Manual setup on personal webserver, or access required by TeachBooks or TU Delft OIT 🚧 | -| Book access with SSO | Only available for GitHub pages on GitHub Enterprise of TU Delft ❌, optional with custom URL ✅ | Optional ✅ | +| Book access with SSO | Only available for GitHub pages on GitHub Enterprise of TU Delft 🎓, optional with custom URL ✅ | Optional ✅ | | Access to source code | Private (if part of organization linked to educational account) /public / internally TU Delft (on GitHub Enterprise of TU Delft) 👥 | Private / public (read-only) / internally TU Delft, editing requires requires SSO login 👥 👀 | | GitHub Desktop | Well integrated 😎 | Basic integration 🙂 | | Utteranc.es | Can be linked to same repository 🏷️ | Requires GitHub repository next to GitLab repository 🏷️🏷️| From 2c0f5b8484dc92b7bb8291bd2b2532613234c794 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 28 Oct 2024 18:49:50 +0100 Subject: [PATCH 08/38] Update TeachBooks --- book/external/TeachBooks | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/TeachBooks b/book/external/TeachBooks index f6968d6..21a67f7 160000 --- a/book/external/TeachBooks +++ b/book/external/TeachBooks @@ -1 +1 @@ -Subproject commit f6968d6284d5f75950e502c50c6778d08d0fdf1f +Subproject commit 21a67f72539aa144de54bf05b9b8d24771590771 From 2e21dca12c4e127a6846b2fb0a60861155180e7d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 28 Oct 2024 19:39:41 +0100 Subject: [PATCH 09/38] Update template --- book/external/template | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/template b/book/external/template index 080483e..af9c83a 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit 080483e6865edff26fd125382bac99b13e4d8539 +Subproject commit af9c83ab6f4761ad10307ba090b63ea62dd70000 From 4811a5746d6ea3a34e5ca328aee1e8b26f429ef5 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 28 Oct 2024 19:53:19 +0100 Subject: [PATCH 10/38] Update requirements.txt --- requirements.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/requirements.txt b/requirements.txt index 2efce34..7a4c02c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,7 +3,7 @@ teachbooks sphinx-inline-tabs jupyterlite-sphinx jupyterbook_patches +download_link_replacer --extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple -sphinx-thebe ~= 0.9.9 -download_link_replacer @ git+https://gitlab.tudelft.nl/mude/sphinx-download-link-replacer +sphinx-thebe ~= 0.9.9 \ No newline at end of file From 8bcb128b0c26565887ed25d5eddbc486e952b399 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 28 Oct 2024 20:08:35 +0100 Subject: [PATCH 11/38] bump --- book/jupyterlite-config.json | 10 ---------- requirements.txt | 3 ++- 2 files changed, 2 insertions(+), 11 deletions(-) delete mode 100644 book/jupyterlite-config.json diff --git a/book/jupyterlite-config.json b/book/jupyterlite-config.json deleted file mode 100644 index eac0d3a..0000000 --- a/book/jupyterlite-config.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "XeusPythonEnv": { - "packages": [ - "numpy", - "matplotlib", - "ipywidgets", - "scipy" - ] - } -} \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 7a4c02c..ada3d80 100644 --- a/requirements.txt +++ b/requirements.txt @@ -5,5 +5,6 @@ jupyterlite-sphinx jupyterbook_patches download_link_replacer + --extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple -sphinx-thebe ~= 0.9.9 \ No newline at end of file +sphinx-thebe ~= 0.9.9 From bf305e5dc1530267282a2e4cba33507280a3ef39 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 29 Oct 2024 14:07:39 +0100 Subject: [PATCH 12/38] Update template --- book/external/template | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/template b/book/external/template index af9c83a..4060a0e 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit af9c83ab6f4761ad10307ba090b63ea62dd70000 +Subproject commit 4060a0e77bfeb97d11e5f554612063305fba616e From 1be1e4258a710e93541d69423e39095901ea6139 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 30 Oct 2024 12:22:09 +0100 Subject: [PATCH 13/38] added how to do wheels --- book/features/live_code.ipynb | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb index a2dfb95..64f43d2 100644 --- a/book/features/live_code.ipynb +++ b/book/features/live_code.ipynb @@ -128,7 +128,22 @@ "\n", "```python\n", "%pip install package_name\n", - "```\n" + "```\n", + "\n", + "If you have some custom packages you can also create a wheel to import. Therefore, create a wheel from your package by running this in the root directoy of your package: \n", + "\n", + "```\n", + "python setup.py bdist_wheel\n", + "```\n", + "\n", + "Copy the wheel from `dist/.whl` to your book and import the package from within a notebook using:\n", + "\n", + "```python\n", + "import micropip\n", + "await micropip.install('/.whl')\n", + "```\n", + "\n", + "Preferably with the tag `thebe-remove-input-init`." ] }, { From 68114e395f0d57704d046436d5c82f1041c41616 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 30 Oct 2024 12:23:02 +0100 Subject: [PATCH 14/38] Update live_code.ipynb --- book/features/live_code.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb index 64f43d2..6e33f52 100644 --- a/book/features/live_code.ipynb +++ b/book/features/live_code.ipynb @@ -132,7 +132,7 @@ "\n", "If you have some custom packages you can also create a wheel to import. Therefore, create a wheel from your package by running this in the root directoy of your package: \n", "\n", - "```\n", + "```shell\n", "python setup.py bdist_wheel\n", "```\n", "\n", From 57a6e8ad7caad7edbc5c0ca1818858bb189c5603 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 30 Oct 2024 12:26:29 +0100 Subject: [PATCH 15/38] Update live_code.ipynb --- book/features/live_code.ipynb | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb index 6e33f52..ff42ea6 100644 --- a/book/features/live_code.ipynb +++ b/book/features/live_code.ipynb @@ -124,12 +124,7 @@ "\n", "This will install the packages: Micropip will look at the Pyodide package index, but also at the general PyPi index. If a package is pure python (i.e. no C extensions), then it can also be used by Pyodide.\n", "\n", - "If the packages are not included in Pyodide, you can use `pip:\n", - "\n", - "```python\n", - "%pip install package_name\n", - "```\n", - "\n", + "### Custom packages\n", "If you have some custom packages you can also create a wheel to import. Therefore, create a wheel from your package by running this in the root directoy of your package: \n", "\n", "```shell\n", @@ -143,7 +138,14 @@ "await micropip.install('/.whl')\n", "```\n", "\n", - "Preferably with the tag `thebe-remove-input-init`." + "Preferably with the tag `thebe-remove-input-init`.\n", + "\n", + "### Other packages not in Pyodide but on PyPI\n", + "If the packages are not included in Pyodide, you can use `pip:\n", + "\n", + "```python\n", + "%pip install package_name\n", + "```" ] }, { From bda88a9e316c23b594bf10287d1562e14888d22e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 30 Oct 2024 14:24:40 +0100 Subject: [PATCH 16/38] Updated OIT text --- book/installation-and-setup/collab.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/book/installation-and-setup/collab.md b/book/installation-and-setup/collab.md index 3a983fd..53c4532 100644 --- a/book/installation-and-setup/collab.md +++ b/book/installation-and-setup/collab.md @@ -14,4 +14,5 @@ For the editing process, establish some practical rules on whether to use issues Choose whether you want to share your source code and built book privately, internally or publicly. In any case, you need to obey copyright-rules. We advise public repositories and books in line with a vision on open education. ## Publishing via Open Interactive Textbooks TU Delft -Decide on whether or not to publish your book via Open Interactive Textbooks TU Delft. Publishing will give you a copyright check, ISBN, DOI number, and registration in several shared databases but heavily limits the amount of changes you can make to your book. In case of editing a book for a course during that actual course and if your book is worth publishing outside of your course's content, we advise only publishing an archived version of your book whenever the academic year is over. \ No newline at end of file +Decide on whether or not to publish your book via Open Interactive Textbooks TU Delft. Publishing will give you a copyright check, ISBN or DOI number, and registration in several shared databases but limits the amount of changes you can make to your book: for substantial changes a new published version is needed with an updated copyright checks. Small changes like typos can always be made, which are processed in the published version every hour. +In case of editing a book for a course during that actual course and/or your book has limited value outside your course's content, we advise you only to publish an archived version of your book whenever the academic year is over. \ No newline at end of file From ec6ca7ddf996d673e717791b5bdddc192a0a7c9b Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 31 Oct 2024 16:58:34 +0100 Subject: [PATCH 17/38] Update description in teachbooks package --- book/_toc.yml | 2 - book/external/TeachBooks | 2 +- book/features/custom_toc.md | 37 ------------------- .../jupyter-book-setup.md | 26 +------------ book/workflows/edit_book.md | 27 ++++++++------ 5 files changed, 18 insertions(+), 76 deletions(-) delete mode 100644 book/features/custom_toc.md diff --git a/book/_toc.yml b/book/_toc.yml index a2c7ed8..6dc8c7d 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -46,8 +46,6 @@ parts: - file: external/TeachBooks/README.md title: TeachBooks Package - file: external/deploy-book-workflow/README.md - - file: features/remove_from_publish - - file: features/custom_toc.md - file: features/custom_download.md - file: external/Nested-Books/README.md - file: external/Sphinx-Image-Inverter/README.md diff --git a/book/external/TeachBooks b/book/external/TeachBooks index 21a67f7..6fcc3b8 160000 --- a/book/external/TeachBooks +++ b/book/external/TeachBooks @@ -1 +1 @@ -Subproject commit 21a67f72539aa144de54bf05b9b8d24771590771 +Subproject commit 6fcc3b860e78500d74b14bc5617c2e21ac7981ac diff --git a/book/features/custom_toc.md b/book/features/custom_toc.md deleted file mode 100644 index 77cbae7..0000000 --- a/book/features/custom_toc.md +++ /dev/null @@ -1,37 +0,0 @@ -(remove-from-publish)= -# Exclude parts of book from published book - -```{admonition} User types -:class: tip -This section is useful for user type 3-5. -``` - -A feature to enable viewing of work-in-progress (e.g., in the draft book) or testing of content (e.g., interactive programming pages) while preventing students from seeing it is available via the {ref}`teachbooks-package `. Lines of text in a `*.yml` file can be removed prior to the book build process by surrounding the lines with a tag `REMOVE-FROM-PUBLISH`. For example, pages in a draft book (e.g., `main` branch) can be manually stripped out of the table of contents when a merge request from `main` to `publish` is made. This prevents the page being included in the published book. Pages marked with this feature are still visible in the draft book and books build from source on personal computers. Lines tagged in the configuration file `_config.yml` can be used in exactly the same manner. The tag is applied as follows: - -``` -format: jb-book -root: intro - -parts: - - caption: ... - chapters: - - file: ... - ... -# START REMOVE-FROM-PUBLISH - - file: files_to_remove -# END REMOVE-FROM-PUBLISH -``` -There is no limit to the number of stripped sections, they can be sequential and indentation does not matter. - -To invoke the tag and remove content during the book build process, use the following optional argument when building the book with the `teachbooks` package: - -``` -teachbooks build --publish book -``` - -Note that `teachbooks build book` would build a book without stripping the tagged lines, just as `jupyter-book build book` would. - -```{note} -The `REMOVE-FROM-PUBLISH` feature was originally deployed using Bash and Shell scripts in the pipeline of our book build processes. The MUDE book contained the scripts on the server, whereas the `interactivetextbooks-citg` contained this in the GitLab CI files or `*.sh` scripts. These workflows will eventually be replaced with a simplified pipeline setup (i.e., a GitLab CI file or GitHub workflow) that uses the commands `teachbooks build book` and `teachbook build --publish book` for the published and draft versions of the book, resepctively. We recommend you do the same. A working example can be found in our [Template repository workflow on GitHub](https://github.com/TeachBooks/deploy-book-workflow/blob/main/.github/workflows/deploy-book.yml) or in the [MUDE book on GitLab](https://gitlab.tudelft.nl/mude/book/-/blob/main/.gitlab-ci.yml?ref_type=heads). -``` - diff --git a/book/installation-and-setup/jupyter-book-setup.md b/book/installation-and-setup/jupyter-book-setup.md index 7f90828..9c9c2d2 100644 --- a/book/installation-and-setup/jupyter-book-setup.md +++ b/book/installation-and-setup/jupyter-book-setup.md @@ -19,7 +19,7 @@ Don't forget to add the package `teachbooks` in the `requirements.txt` files in As soon as you've installed your book environment with jupyter-book you can build your book locally. The official Jupyter book documentation is quite extensive. You can navigate to the directory where your book is to leave out the `path-to-book`. ``` -teachbooks build --all +teachbooks build ``` Alternatively: ``` @@ -45,27 +45,3 @@ Terminal :class: tip, dropdown Bookmark the (local) file location for easy access! ``` -(setup-local-server)= -## View the book using a local webserver - -```{admonition} Note -:class: tip -If your book consists only of markdown files the local python server is not necessary and you can just view the book locally. -``` - -Some features like JupyterLite and Grasple only work when a webserver serves the HTML content for a book. Rather than building the book in your repository and updating the website on the internet, you can use a local webserver to view the book: -1. Make sure you have the TeachBooks Python package installed (e.g., `pip install teachbooks`) -2. Start a server from the command line with: `teachbooks serve` -3. The command line output will return the URL where you can access your book -4. You should reload the page if you are editing and rebuilding the book. You can try `CTRL+R` `ctrl`+`F5`. If this does not work, on Chrome try right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`. -5. All interactive features like the JupyterLite consoles, Grasple/H5p iframe exercises, Sphinx-thebe python interactivity and HTML/Javascript elements should now work as well. -6. When you no longer need the server, simply run `teachbooks serve stop` - -### How to create a local server without the TeachBooks package - -Here is how to set up a local server with only standard Python libraries: - -1. Start a server from the command line with: `python -m http.server -b 127.0.0.1` (add ` &` if you want to keep using the terminal for other tasks). -2. Port 8000 is usually used by default, but depending on your OS it will tell you in the output. -3. To visit your site, just enter the address in your web browser, followed by a colon, and then the port number. By default, that would be: `127.0.0.1:8000`. -4. You will get a website that looks like a file browser, to visit your site just navigate to `book/_build/html/` (if you've started this command from this folder you see the book immediately) \ No newline at end of file diff --git a/book/workflows/edit_book.md b/book/workflows/edit_book.md index 904c1ea..3d9bf59 100644 --- a/book/workflows/edit_book.md +++ b/book/workflows/edit_book.md @@ -366,21 +366,30 @@ Demonstration, video available [here](https://youtu.be/2ttjBevkEP8) 2. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy! Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar. + You will firstly need to actiavte the right environment. Type the following command: `conda activate jupyter-book-env` (or the environment in which you have installed the TeachBooks package) -Then we can build the book locally. Make sure you are in the right repository in VS code and type the folloing command: +Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command: -`jupyter-book build book` +``` +teachbooks build +``` +Alternatively: +``` +jupyter-book build --all +``` -Where book is the name of the folder containing all the files that make up your book. After `jupyter-book` is done running you will get the following: +Note: use `--all` for the jupyter-book whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book. + +Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following: ```{figure} ../figures/buildbook.PNG -Output. +Output ``` Paste the last line into your browser to see the updated changes. @@ -391,6 +400,9 @@ Sometimes there are problems building the book. It could be that the building re `pip install -r requirements.txt --upgrade` ``` + +If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server] + 3. If you are satisfied with your changes, you can select the files ready to be added to Git-timeline (staging) For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu: @@ -419,13 +431,6 @@ In the bottom left corner, next to the branch name, click the "Synchronize Chang ```{figure} ../images/git-push.png After committing, click the 🔄 button to push our changes to the remote repository. - -```{Note} - -Missing from this chapter: startup python server. - -You can read more about it [here](/book/installation-and-setup/jupyter-book-setup.md) -``` ```` ````{tab-item} ... GitHub Desktop From 681af875ea3c796010792e906c8f36cc96b167c2 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 31 Oct 2024 17:02:53 +0100 Subject: [PATCH 18/38] Update _toc.yml --- book/_toc.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index 6dc8c7d..8475d23 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -44,7 +44,6 @@ parts: - file: features/overview sections: - file: external/TeachBooks/README.md - title: TeachBooks Package - file: external/deploy-book-workflow/README.md - file: features/custom_download.md - file: external/Nested-Books/README.md From d2209739351ebe313c71f14b74d72dfd0d90959d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 31 Oct 2024 17:10:17 +0100 Subject: [PATCH 19/38] add teachbooks instructions everywhere --- book/workflows/edit_book.md | 82 +++++++++++++++++++++++++++---------- 1 file changed, 60 insertions(+), 22 deletions(-) diff --git a/book/workflows/edit_book.md b/book/workflows/edit_book.md index 3d9bf59..99b78ea 100644 --- a/book/workflows/edit_book.md +++ b/book/workflows/edit_book.md @@ -360,6 +360,7 @@ The steps above are demonstrated in the figure below, all steps are elaborated o name: user5_demo --- Demonstration, video available [here](https://youtu.be/2ttjBevkEP8) +``` 1. Make some changes to a file in for example VS Code and save them. @@ -367,7 +368,7 @@ Demonstration, video available [here](https://youtu.be/2ttjBevkEP8) Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar. -You will firstly need to actiavte the right environment. Type the following command: +You will firstly need to activate the right environment. Type the following command: `conda activate jupyter-book-env` @@ -378,7 +379,9 @@ Then we can build the book locally. Make sure you are in the right repository in ``` teachbooks build ``` + Alternatively: + ``` jupyter-book build --all ``` @@ -440,21 +443,32 @@ After committing, click the 🔄 button to push our changes to the remote reposi 2. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy! Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar. -You will firstly need to actiavte the right environment. Type the following command: + +You will firstly need to activate the right environment. Type the following command: `conda activate jupyter-book-env` (or the environment in which you have installed the TeachBooks package) -Then we can build the book locally. Make sure you are in the right repository in VS code and type the folloing command: +Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command: -`jupyter-book build book` +``` +teachbooks build +``` -Where book is the name of the folder containing all the files that make up your book. After `jupyter-book` is done running you will get the following: +Alternatively: + +``` +jupyter-book build --all +``` + +Note: use `--all` for the jupyter-book whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book. + +Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following: ```{figure} ../figures/buildbook.PNG -Output. +Output ``` Paste the last line into your browser to see the updated changes. @@ -465,6 +479,9 @@ Sometimes there are problems building the book. It could be that the building re `pip install -r requirements.txt --upgrade` ``` + +If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server] + 3. If you are satisfied with your changes, you can select the files ready to be added to Git-timeline (staging) The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*. @@ -487,12 +504,6 @@ Alternatively, you can also click on `Push origin` in the top bar. Example Image -```{Note} - -Missing from this chapter: startup python server. - -You can read more about it [here](/book/installation-and-setup/jupyter-book-setup.html#view-the-book-using-a-local-webserver) -``` ```` ````` `````` @@ -537,21 +548,32 @@ Choose one of the options to resolve the merge conflict. You now have updated yo 4. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy! Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar. -You will firstly need to actiavte the right environment. Type the following command: + +You will firstly need to activate the right environment. Type the following command: `conda activate jupyter-book-env` (or the environment in which you have installed the TeachBooks package) -Then we can build the book locally. Make sure you are in the right repository in VS code and type the folloing command: +Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command: -`jupyter-book build book` +``` +teachbooks build +``` -Where book is the name of the folder containing all the files that make up your book. After `jupyter-book` is done running you will get the following: +Alternatively: + +``` +jupyter-book build --all +``` + +Note: use `--all` for the jupyter-book whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book. + +Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following: ```{figure} ../figures/buildbook.PNG -Output. +Output ``` Paste the last line into your browser to see the updated changes. @@ -562,6 +584,9 @@ Sometimes there are problems building the book. It could be that the building re `pip install -r requirements.txt --upgrade` ``` + +If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server] + 5. Select the files ready to be added to Git-timeline (staging) For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu: @@ -611,21 +636,32 @@ Choose one of the options to resolve the merge conflict. You now have updated yo 4. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy! Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar. -You will firstly need to actiavte the right environment. Type the following command: + +You will firstly need to activate the right environment. Type the following command: `conda activate jupyter-book-env` (or the environment in which you have installed the TeachBooks package) -Then we can build the book locally. Make sure you are in the right repository in VS code and type the folloing command: +Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command: -`jupyter-book build book` +``` +teachbooks build +``` -Where book is the name of the folder containing all the files that make up your book. After `jupyter-book` is done running you will get the following: +Alternatively: + +``` +jupyter-book build --all +``` + +Note: use `--all` for the jupyter-book whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book. + +Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following: ```{figure} ../figures/buildbook.PNG -Output. +Output ``` Paste the last line into your browser to see the updated changes. @@ -637,6 +673,8 @@ Sometimes there are problems building the book. It could be that the building re ``` +If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server] + 5. The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*.
From ece5bae3039d0c8c72e2dca0009ead9b18efe63b Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 1 Nov 2024 10:03:50 +0100 Subject: [PATCH 20/38] Added jupyterbook-patches --- .gitmodules | 3 +++ book/_toc.yml | 1 + book/external/JupyterBook-Patches | 1 + 3 files changed, 5 insertions(+) create mode 160000 book/external/JupyterBook-Patches diff --git a/.gitmodules b/.gitmodules index 9f34e0d..e2fb864 100644 --- a/.gitmodules +++ b/.gitmodules @@ -19,3 +19,6 @@ [submodule "book/external/Sphinx-Image-Inverter"] path = book/external/Sphinx-Image-Inverter url = https://github.com/TeachBooks/Sphinx-Image-Inverter.git +[submodule "book/external/JupyterBook-Patches"] + path = book/external/JupyterBook-Patches + url = https://github.com/TeachBooks/JupyterBook-Patches.git diff --git a/book/_toc.yml b/book/_toc.yml index 8475d23..74e3105 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -48,6 +48,7 @@ parts: - file: features/custom_download.md - file: external/Nested-Books/README.md - file: external/Sphinx-Image-Inverter/README.md + - file: external/JupyterBook-Patches/README.md - file: features/interactive_element.ipynb sections: - file: features/grasple.md diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches new file mode 160000 index 0000000..3c88310 --- /dev/null +++ b/book/external/JupyterBook-Patches @@ -0,0 +1 @@ +Subproject commit 3c88310402d6075ff187c5b7295d30fc412ffe75 From 211acea7c51c3a3e0c5c3bdf2410a9f77c047a13 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 1 Nov 2024 10:07:40 +0100 Subject: [PATCH 21/38] Added download link replacer --- .gitmodules | 3 +++ book/external/Download-Link-Replacer | 1 + 2 files changed, 4 insertions(+) create mode 160000 book/external/Download-Link-Replacer diff --git a/.gitmodules b/.gitmodules index e2fb864..0b07f19 100644 --- a/.gitmodules +++ b/.gitmodules @@ -22,3 +22,6 @@ [submodule "book/external/JupyterBook-Patches"] path = book/external/JupyterBook-Patches url = https://github.com/TeachBooks/JupyterBook-Patches.git +[submodule "book/external/Download-Link-Replacer"] + path = book/external/Download-Link-Replacer + url = https://github.com/TeachBooks/Download-Link-Replacer.git diff --git a/book/external/Download-Link-Replacer b/book/external/Download-Link-Replacer new file mode 160000 index 0000000..d8b40ef --- /dev/null +++ b/book/external/Download-Link-Replacer @@ -0,0 +1 @@ +Subproject commit d8b40efb145a01737c677e638a30a8bbefbaa775 From fd546cc2ea3b300f96b9c9a3b4f88543a4e93e6d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 1 Nov 2024 10:15:10 +0100 Subject: [PATCH 22/38] Improved titles sphinx extensions --- book/_toc.yml | 2 +- book/external/Download-Link-Replacer | 2 +- book/external/Sphinx-Image-Inverter | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/book/_toc.yml b/book/_toc.yml index 74e3105..cbe770b 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -45,8 +45,8 @@ parts: sections: - file: external/TeachBooks/README.md - file: external/deploy-book-workflow/README.md - - file: features/custom_download.md - file: external/Nested-Books/README.md + - file: features/custom_download.md - file: external/Sphinx-Image-Inverter/README.md - file: external/JupyterBook-Patches/README.md - file: features/interactive_element.ipynb diff --git a/book/external/Download-Link-Replacer b/book/external/Download-Link-Replacer index d8b40ef..8fc4a37 160000 --- a/book/external/Download-Link-Replacer +++ b/book/external/Download-Link-Replacer @@ -1 +1 @@ -Subproject commit d8b40efb145a01737c677e638a30a8bbefbaa775 +Subproject commit 8fc4a376870afacba5351c731f55130dfa88d3fb diff --git a/book/external/Sphinx-Image-Inverter b/book/external/Sphinx-Image-Inverter index fe20415..e43f1f6 160000 --- a/book/external/Sphinx-Image-Inverter +++ b/book/external/Sphinx-Image-Inverter @@ -1 +1 @@ -Subproject commit fe204154a4ba19a59ae5a657cb52368b939ae3a4 +Subproject commit e43f1f65f5db3a10191d1baa983e51d1cb7603e9 From 300d5b23f5bc57a9fd7a38816d87d0eac9105105 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 1 Nov 2024 10:20:50 +0100 Subject: [PATCH 23/38] clarified TOC more --- book/external/Nested-Books | 2 +- book/external/deploy-book-workflow | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/book/external/Nested-Books b/book/external/Nested-Books index cc1d35d..60b4678 160000 --- a/book/external/Nested-Books +++ b/book/external/Nested-Books @@ -1 +1 @@ -Subproject commit cc1d35d73558dc5787ede7c4552fb35e9ba82a46 +Subproject commit 60b467844b5f00f59e4d9f9a2e2dbc7e80534706 diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow index c9161cf..449e458 160000 --- a/book/external/deploy-book-workflow +++ b/book/external/deploy-book-workflow @@ -1 +1 @@ -Subproject commit c9161cf168cf24edcf0372172ecec5ad86ace64e +Subproject commit 449e4588d573287a2b6eb4d8fda8e57a26d275e6 From 39b3d16f788eb6b2369616a232449416194c3fd6 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 1 Nov 2024 10:22:50 +0100 Subject: [PATCH 24/38] Improved headers teachbook features --- book/features/interactive_element.ipynb | 2 +- book/features/live_code.ipynb | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/book/features/interactive_element.ipynb b/book/features/interactive_element.ipynb index c737ebc..75bd000 100644 --- a/book/features/interactive_element.ipynb +++ b/book/features/interactive_element.ipynb @@ -7,7 +7,7 @@ "hidePrompt": true }, "source": [ - "# Interactive elements not including Python\n", + "# Interactive content: Elements not including Python\n", "\n", "To add interactivity to the book, you can make use of interactive elements which are embedded in the book. You've four options:\n", "\n", diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb index ff42ea6..3b46331 100644 --- a/book/features/live_code.ipynb +++ b/book/features/live_code.ipynb @@ -4,7 +4,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Run Python inside your book with Sphinx-thebe\n", + "# Interactive elements: Run Python inside your book\n", "\n", "```{admonition} User types\n", ":class: tip\n", From 914d33c909717022776851722b2a9e9ca94d2507 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 1 Nov 2024 10:28:55 +0100 Subject: [PATCH 25/38] Update tools.md --- book/installation-and-setup/tools.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/installation-and-setup/tools.md b/book/installation-and-setup/tools.md index a0156cc..dc23c21 100644 --- a/book/installation-and-setup/tools.md +++ b/book/installation-and-setup/tools.md @@ -38,7 +38,7 @@ Editing the book can happen both locally as online on GitHub/GitLab. If done loc On GitHub we developed a [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). For a private repository, there is an extensive but limited amount of actions-minutes required for published your book. If this proves to be a limit, consider applying for [Teacher benefits](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers) or joining the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft). -On GitLab a webserver is required to process book-changes online. Both we and other people at TU Delft have a simplistic workflow which can be used when you're set up on those Git environments and webservers. If you want to use GitLab but still want to make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in an active editing-phase since constant copyright checks have to be performed. The amount of computing power available is dependent on how you set the server yourself. +On GitLab a webserver is required to process book-changes online. Both we and other people at TU Delft have a simplistic workflow which can be used when you're set up on those Git environments and webservers. This simplistic workflow doesn't build all branches, is not easily adaptable, doesn't cache environments, doesn't give a visual summary, and doesn't allow for parallel processes (for every build a runner needs to be assigned for which there's typically only one available). If you want to use GitLab but still want to make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in an active editing-phase since constant copyright checks have to be performed. The amount of computing power available is dependent on how you set the server yourself. ### 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). @@ -67,7 +67,7 @@ Here's a table summarizing the information: | | GitHub | GitLab | |--|----------|-------------| | Book url | GitHub pages (`.github.io/`), for TU Delft GitHub Enterprise with SSO a random URL (`.github.io/`), or custom url `./`> 🌐 | TeachBooks (`teachbooks.tudelft.nl/`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/`) 🎓 | -| Real-time book editing | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) 🚀 | Automated but simplistic (one or two versions, command-line interface) 🛵 For TU Delft OIT: restricted adaptations because of copyright checks 🚫 | +| Real-time book editing | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) 🚀 | Automated but simplistic (not easily adaptable, no caching environments, no visual summaries, no parallel processes) 🛵 For TU Delft OIT: restricted adaptations because of copyright checks 🚫 | | Setting up book website | Immediate and automated with [template](../external/template/README.md) ⚡️ | Manual setup on personal webserver, or access required by TeachBooks or TU Delft OIT 🚧 | | Book access with SSO | Only available for GitHub pages on GitHub Enterprise of TU Delft 🎓, optional with custom URL ✅ | Optional ✅ | | Access to source code | Private (if part of organization linked to educational account) /public / internally TU Delft (on GitHub Enterprise of TU Delft) 👥 | Private / public (read-only) / internally TU Delft, editing requires requires SSO login 👥 👀 | From 90280ef5b55c7a15333ce49faf06f5fed7e9f1b0 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 1 Nov 2024 10:29:40 +0100 Subject: [PATCH 26/38] Update live_code.ipynb --- book/features/live_code.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb index 3b46331..84e5d01 100644 --- a/book/features/live_code.ipynb +++ b/book/features/live_code.ipynb @@ -4,7 +4,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Interactive elements: Run Python inside your book\n", + "# Interactive content: Run Python inside your book\n", "\n", "```{admonition} User types\n", ":class: tip\n", From 166a45a25bc6dca988decd2e9eaeefdf8c082961 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 1 Nov 2024 10:31:38 +0100 Subject: [PATCH 27/38] Update TeachBooks --- book/external/TeachBooks | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/TeachBooks b/book/external/TeachBooks index 6fcc3b8..0aaef7a 160000 --- a/book/external/TeachBooks +++ b/book/external/TeachBooks @@ -1 +1 @@ -Subproject commit 6fcc3b860e78500d74b14bc5617c2e21ac7981ac +Subproject commit 0aaef7ab52bb21d42b1a1e37bb9de6bf7c4d3469 From 6ec3debda24c36442b3b703f1cae3e36ae2da5ad Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 1 Nov 2024 11:23:00 +0100 Subject: [PATCH 28/38] Update _config.yml --- book/_config.yml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index 089e0ba..4e6a40f 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -19,12 +19,10 @@ html: sphinx: extra_extensions: - sphinx_inline_tabs - - jupyterlite_sphinx - sphinx.ext.imgconverter - download_link_replacer - jupyterbook_patches config: - jupyterlite_config: jupyterlite-config.json html_js_files: - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js thebe_config: @@ -36,4 +34,5 @@ sphinx: use_issues_button : true launch_buttons: thebe: true - html_show_copyright: false \ No newline at end of file + html_show_copyright: false + html_last_updated_fmt: '%B %-d, %Y' \ No newline at end of file From da684626097fc2a1a2d2699910e2357ab1f98bab Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 1 Nov 2024 11:34:12 +0100 Subject: [PATCH 29/38] close hyperlink footer --- book/_config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_config.yml b/book/_config.yml index 4e6a40f..70201cb 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -1,5 +1,5 @@ title: TeachBooks Manual -author: TeachBooks Team from Delft University of Technology, built with TeachBooks and Jupyter Book, CC BY 4.0 +author: TeachBooks Team from Delft University of Technology, built with TeachBooks and Jupyter Book, CC BY 4.0 logo: images/Logo_without_background.png From cf12dc41648ff3f430ff3a1dd9adb70119943ec6 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 4 Nov 2024 09:13:44 +0100 Subject: [PATCH 30/38] TOC update --- .../choose_platforms.md | 29 ------------------- book/installation-and-setup/organize-team.md | 2 +- book/installation-and-setup/tools.md | 2 +- 3 files changed, 2 insertions(+), 31 deletions(-) delete mode 100644 book/installation-and-setup/choose_platforms.md diff --git a/book/installation-and-setup/choose_platforms.md b/book/installation-and-setup/choose_platforms.md deleted file mode 100644 index 2a4232a..0000000 --- a/book/installation-and-setup/choose_platforms.md +++ /dev/null @@ -1,29 +0,0 @@ -# GitHub vs GitLab - -```{admonition} User types -:class: tip -This page is useful for user type 3-5. -``` - -Now that you can start, there's a first choice to be made, where to host your book: - -- Github allows you to host your book on the GitHub server using GitHub pages (to be recognized by the `.github.io/` url, for example the [template book](https://teachbooks.github.io/template/)), which takes all the steps of hosting out of your hands. You can also use a custom owned URL, although this requires some additional skills. On TU Delft's GitLab you need a webserver, which is offered by TeachBooks (to be recognized by the url `teachbooks.tudelft.nl/`, for example [this manual](https://teachbooks.tudelft.nl/jupyter-book-manual)) as the TU Delft OIT team (to be recognized by the url `interactivetextbooks.tudelft.nl/`, for example [the TU Delft OIT demo book](https://interactivetextbooks.tudelft.nl/open-textbooks-demonstration/)). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in the editing-phase. -- 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 GitHub we developed a [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). On GitLab both we and other people at TU Delft have a more simplistic workflow which can be used when you're set up on those Git environments and webservers. If you want to use GitLab and make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github) -- Because we’re in control on the server connected to GitLab, we can set up SSO login for visitors of the website. This is not an option for GitHub because we don’t own the server. -- Both GitLab and GitHub allow for extensive options for visibility of the source code. If you're using GitHub pages, you need a free organization linked to a free eduational account. The TU Delft GitLab requires SSO login for editing the book. Although this is useful for TU Delft employees, it limits the collaboration with people outside of TU Delft. -- GitHub has a nice integration with the [GitHub Desktop application](git-setup_local.md). For GitLab it works as well, but has less functionality. -- [Utteranc.es](../basic-features/utterances.md) requires a GitHub repository to host the discussions. If you're using a GitLab repository, you need a separate GitHub repository and the discussions and book content is not at the same place. - -If you have doubt about this choice, we advise you to start on GitHub. Moving/duplicating your content to GitLab or hosting to a custom URL is always possible at a later stage. - -Here's a table summarizing the information: -| | GitHub | GitLab | -|--|----------|-------------| -| Website to view book online | GitHub pages (`.github.io/`) or custom URL 🌐 | TeachBooks (`teachbooks.tudelft.nl/`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/`) 🎓 | -| Setting up book website | Immediate and automated with [template](../external/template/README.md) ⚡️ | Access required by TeachBooks or TU Delft OIT 🚧 | -| Updating book website | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) 🚀 | Automated but simplistic (one or two versions, command-line interface) 🛵 | -| Student book access with SSO | Not available for GitHub pages ❌, optional with custom URL ✅ | Optional ✅ | -| Teacher/TA access to Git repository | Private (if part of organization linked to educational account) /public 👀 | Private / public / internally TU Delft, editing requires requires SSO login 👥 | -| GitHub Desktop | Well integrated 😎 | Basic integration 🙂 | -| Utteranc.es | Can be linked to same repository 🏷️ | Requires GitHub repository next to GitLab repository 🏷️🏷️| \ No newline at end of file diff --git a/book/installation-and-setup/organize-team.md b/book/installation-and-setup/organize-team.md index 3c4f7b0..8cc81c3 100644 --- a/book/installation-and-setup/organize-team.md +++ b/book/installation-and-setup/organize-team.md @@ -1,4 +1,4 @@ -# Organize your editing team and tools +# Organize your editing team, tools and URL ```{admonition} User types :class: tip diff --git a/book/installation-and-setup/tools.md b/book/installation-and-setup/tools.md index dc23c21..2ca353b 100644 --- a/book/installation-and-setup/tools.md +++ b/book/installation-and-setup/tools.md @@ -1,4 +1,4 @@ -# Tools +# URLs and tools The setup of tools is dependent on agreements you've made on collaboration. ## Collaboration in readme From c41c48ea525e6f5609d7bbe3d56df8c27ff6ca29 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 4 Nov 2024 10:19:11 +0100 Subject: [PATCH 31/38] restructure team and tools --- book/_toc.yml | 6 ++---- book/installation-and-setup/collab.md | 7 ++++++- book/installation-and-setup/organize-team.md | 8 -------- book/installation-and-setup/tools.md | 12 +++++++++--- 4 files changed, 17 insertions(+), 16 deletions(-) delete mode 100644 book/installation-and-setup/organize-team.md diff --git a/book/_toc.yml b/book/_toc.yml index cbe770b..a5cd7c1 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -21,10 +21,8 @@ parts: - file: workflows/edit_book - file: workflows/check_changes_online - file: workflows/merge_request - - file: installation-and-setup/organize-team - sections: - - file: installation-and-setup/collab - - file: installation-and-setup/tools + - -file: installation-and-setup/collab + - file: installation-and-setup/tools - file: installation-and-setup/creating_content.md - caption: Features chapters: diff --git a/book/installation-and-setup/collab.md b/book/installation-and-setup/collab.md index 53c4532..1742531 100644 --- a/book/installation-and-setup/collab.md +++ b/book/installation-and-setup/collab.md @@ -1,4 +1,9 @@ -# Team and collaboration +# Organize editing team, collaboration and visibility + +```{admonition} User types +:class: tip +This page is useful for user type 4-5. +``` ## Roles and responsibilities To ensure smooth collaboration, it is essential to define the roles and responsibilities within your team. Firstly, designate who will be in charge of team organization ('administrators') who should be at least user type 4. Additionally, assign 'maintainers' responsible for combining content, also requiring at least user type 4. 'Editors' should be identified for editing and reviewing content, requiring at least user type 3. diff --git a/book/installation-and-setup/organize-team.md b/book/installation-and-setup/organize-team.md deleted file mode 100644 index 8cc81c3..0000000 --- a/book/installation-and-setup/organize-team.md +++ /dev/null @@ -1,8 +0,0 @@ -# Organize your editing team, tools and URL - -```{admonition} User types -:class: tip -This page is useful for user type 4-5. -``` - -If you want to create a collaborative book for students, there's a few agreements you should make to enhance collaboration and student experience. These are written from our own experience, feel free to deviate or provide your own advice! A distinction has been made between organization of teams and tools. \ No newline at end of file diff --git a/book/installation-and-setup/tools.md b/book/installation-and-setup/tools.md index 2ca353b..9e3f6a9 100644 --- a/book/installation-and-setup/tools.md +++ b/book/installation-and-setup/tools.md @@ -1,5 +1,11 @@ -# URLs and tools -The setup of tools is dependent on agreements you've made on collaboration. +# Choose URLs and tools + +```{admonition} User types +:class: tip +This page is useful for user type 4-5. +``` + +The setup of tools and URLs is dependent on agreements you've made on [collaboration](./collab.md). ## Collaboration in readme Provide explanation on how you organize the book-editing and how you'd like to receive feedback in both the readme as the published book. The use of the [issue button](https://jupyterbook.org/en/stable/basics/repository.html#add-a-button-to-open-issues) is advised for the published book. @@ -64,7 +70,7 @@ GitHub has a nice integration with the [GitHub Desktop application](git-setup_lo ### Summary Here's a table summarizing the information: -| | GitHub | GitLab | +| | GitHub | TU Delft GitLab | |--|----------|-------------| | Book url | GitHub pages (`.github.io/`), for TU Delft GitHub Enterprise with SSO a random URL (`.github.io/`), or custom url `./`> 🌐 | TeachBooks (`teachbooks.tudelft.nl/`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/`) 🎓 | | Real-time book editing | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) 🚀 | Automated but simplistic (not easily adaptable, no caching environments, no visual summaries, no parallel processes) 🛵 For TU Delft OIT: restricted adaptations because of copyright checks 🚫 | From 0f611b471a80b6a46518ac5057ac80d3ccc06e4f Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 4 Nov 2024 10:19:56 +0100 Subject: [PATCH 32/38] typo --- book/_toc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index a5cd7c1..c484808 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -21,7 +21,7 @@ parts: - file: workflows/edit_book - file: workflows/check_changes_online - file: workflows/merge_request - - -file: installation-and-setup/collab + - file: installation-and-setup/collab - file: installation-and-setup/tools - file: installation-and-setup/creating_content.md - caption: Features From 29f7e080313bc7d2b5ac155f9db62200527be7fc Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 4 Nov 2024 10:20:53 +0100 Subject: [PATCH 33/38] Update creating_content.md --- book/installation-and-setup/creating_content.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/installation-and-setup/creating_content.md b/book/installation-and-setup/creating_content.md index 54ee2e9..876643a 100644 --- a/book/installation-and-setup/creating_content.md +++ b/book/installation-and-setup/creating_content.md @@ -1,4 +1,4 @@ -# Content & Copyright +# Before doing any content: copyright The previous sections have familiarized you with the necessary software for your user type, the basics of Git, and how to collaborate with your team using Git. Now it's time to create your own content. This section will provide an overview of the copy right laws which need to be taking into account when creating and including content at TU Delft! From a39b05059918202c9a1ce4cb20287727b729c610 Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Mon, 4 Nov 2024 11:44:10 +0100 Subject: [PATCH 34/38] update --- book/features/custom_download.md | 22 ++++++---------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/book/features/custom_download.md b/book/features/custom_download.md index 4ee96cd..f866e2c 100644 --- a/book/features/custom_download.md +++ b/book/features/custom_download.md @@ -9,10 +9,10 @@ You can control the download option of the book in two ways: - Disabling downloading using cell tags `disable-download-page` - Add / replace download link with custom link using `spinhx-download-link-replacer` -## Disabling download +## 1. Disabling download If you add `disable-download-page` as a cell tag to a cell in a python notebook, the download button ({fa}`download`) will disappear from the topright corner. The cell tag can be added to any code cell in the notebook. This function might be handy if your page includes code which you don't want the students to see. Be aware that this also removes the option to download a PDF of the page. -## Add/replace download link +## 2. Add/replace download link The download link {fa}`download` --> {fa}`file`{guilabel}`.ipynb` can be replaced by using the following code in any markdown / notebook file: ````md ```{custom_download_link} @@ -26,19 +26,9 @@ An explanation of the options of this command is given on https://gitlab.tudelft A potential application of this functionality is when creating a page in which students have to do some coding. Downloading the page allows the student to save their work and work with their local environment. However, the original source file might include code (jupyterbook formatting, widgets, answers) which is not necessary for students. You can make a copy of the notebook file without these elements and replace the {fa}`file`{guilabel}`.ipynb` link to this custom notebook file. Furthermore, you can add any additional data as an additional {fa}`file`{guilabel}`.zip` file. -### Installation instructions -To make use of this functionality, you have to install the `download_link_replace` package by running the following line in your command line: -``` -pip install git+https://gitlab.tudelft.nl/mude/sphinx-download-link-replacer -``` +### 2.1. Installation instructions + +```{include} book/external/Download-Link_Replacer/README.md -Furthermore, you should add the following line to `requirements.txt` ``` -download_link_replacer @ git+https://gitlab.tudelft.nl/mude/sphinx-download-link-replacer -``` -and to `_config.yml`: -``` -sphinx: - extra_extensions: - - download_link_replacer -``` \ No newline at end of file +book\external\Download-Link-Replacer\README.md \ No newline at end of file From df9d49b34be650f132fc9bf424f1c79f94188e57 Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Mon, 4 Nov 2024 11:53:21 +0100 Subject: [PATCH 35/38] commit change --- book/external/Download-Link-Replacer | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/Download-Link-Replacer b/book/external/Download-Link-Replacer index 8fc4a37..cf0d3c9 160000 --- a/book/external/Download-Link-Replacer +++ b/book/external/Download-Link-Replacer @@ -1 +1 @@ -Subproject commit 8fc4a376870afacba5351c731f55130dfa88d3fb +Subproject commit cf0d3c99f3e0bd549ac2d38d8117f9b9ea5a179c From 29f88d922b171e0d7e75135cabe1793e0b867ef2 Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Mon, 4 Nov 2024 11:59:04 +0100 Subject: [PATCH 36/38] toc change --- book/_toc.yml | 2 +- book/features/custom_download.md | 34 -------------------------------- 2 files changed, 1 insertion(+), 35 deletions(-) delete mode 100644 book/features/custom_download.md diff --git a/book/_toc.yml b/book/_toc.yml index c484808..e875ba8 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -44,7 +44,7 @@ parts: - file: external/TeachBooks/README.md - file: external/deploy-book-workflow/README.md - file: external/Nested-Books/README.md - - file: features/custom_download.md + - file: external/Download-Link-Replacer/README.md - file: external/Sphinx-Image-Inverter/README.md - file: external/JupyterBook-Patches/README.md - file: features/interactive_element.ipynb diff --git a/book/features/custom_download.md b/book/features/custom_download.md deleted file mode 100644 index f866e2c..0000000 --- a/book/features/custom_download.md +++ /dev/null @@ -1,34 +0,0 @@ -# Page download options - -```{admonition} User types -:class: tip -This section is useful for user type 4-5. -``` - -You can control the download option of the book in two ways: - - Disabling downloading using cell tags `disable-download-page` - - Add / replace download link with custom link using `spinhx-download-link-replacer` - -## 1. Disabling download -If you add `disable-download-page` as a cell tag to a cell in a python notebook, the download button ({fa}`download`) will disappear from the topright corner. The cell tag can be added to any code cell in the notebook. This function might be handy if your page includes code which you don't want the students to see. Be aware that this also removes the option to download a PDF of the page. - -## 2. Add/replace download link -The download link {fa}`download` --> {fa}`file`{guilabel}`.ipynb` can be replaced by using the following code in any markdown / notebook file: -````md -```{custom_download_link} -:text: "Custom text" -:replace_default: "True" -``` -```` - -An explanation of the options of this command is given on https://gitlab.tudelft.nl/mude/sphinx-download-link-replacer. - -A potential application of this functionality is when creating a page in which students have to do some coding. Downloading the page allows the student to save their work and work with their local environment. However, the original source file might include code (jupyterbook formatting, widgets, answers) which is not necessary for students. You can make a copy of the notebook file without these elements and replace the {fa}`file`{guilabel}`.ipynb` link to this custom notebook file. Furthermore, you can add any additional data as an additional {fa}`file`{guilabel}`.zip` file. - - -### 2.1. Installation instructions - -```{include} book/external/Download-Link_Replacer/README.md - -``` -book\external\Download-Link-Replacer\README.md \ No newline at end of file From 94183678e7b2f96caaa15ce6eac430d5c845d3eb Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 4 Nov 2024 12:17:33 +0100 Subject: [PATCH 37/38] Update Download-Link-Replacer --- book/external/Download-Link-Replacer | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/Download-Link-Replacer b/book/external/Download-Link-Replacer index cf0d3c9..0412e99 160000 --- a/book/external/Download-Link-Replacer +++ b/book/external/Download-Link-Replacer @@ -1 +1 @@ -Subproject commit cf0d3c99f3e0bd549ac2d38d8117f9b9ea5a179c +Subproject commit 0412e9927b631ec7fba5fbd0aca81ecb8b7e0188 From f2db5de663bf8d8366a45e8977d8b5ca4abc8c47 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 4 Nov 2024 12:40:33 +0100 Subject: [PATCH 38/38] Update Download-Link-Replacer --- book/external/Download-Link-Replacer | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/Download-Link-Replacer b/book/external/Download-Link-Replacer index 0412e99..3a71f4a 160000 --- a/book/external/Download-Link-Replacer +++ b/book/external/Download-Link-Replacer @@ -1 +1 @@ -Subproject commit 0412e9927b631ec7fba5fbd0aca81ecb8b7e0188 +Subproject commit 3a71f4a06093e51f67da4f6b02508fdb34341f38