admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-13 06:45:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updated GitHub workflow in editing section

Browse source
This commit is contained in:
Tom van Woudenberg 2024-05-27 14:38:29 +02:00
parent 8706d9d85b
commit 151494c6af
2 changed files with 7 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

4
book/installation-and-setup/choose_platforms.md
View file

@ -9,7 +9,7 @@ Now that you can start, there's a first choice to be made, where to host your bo
- Github allows you to host your book on the GitHub server using GitHub pages (to be recognized by the `<organization/username>.github.io/<book>` 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/<book>`, 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/<book>`, 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.
- 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.
@ -22,7 +22,7 @@ Here's a table summarizing the information:
|--|----------|-------------|
| Website to view book online | GitHub pages (`<organization/username>.github.io/<book>`) or custom URL 🌐 | TeachBooks (`teachbooks.tudelft.nl/<book>`) or TU Delft OIT (`interactivetextbooks.tudelft.nl/<book>`) 🎓 |
| 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) 🛵 |
| 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 🙂 |

19
book/workflows/check_changes_online.md
View file

@ -15,26 +15,17 @@ Now that you've pushed your changes online, it's time to check the change in the
At the moment this is not possible.
However, what you can do is 'mirror' your GitLab repository to GitHub. This will copy your content automatically (but maximum once every 5 minutes) to GitHub. This allows you to use the TeachBook's GitHub actions.
Instructions on how to set up mirroring are provided here: https://gitlab.tudelft.nl/help/user/project/repository/mirror/index#update-a-mirror
Instructions on how to set up mirroring are provided here: https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github
````
````{tab-item} In GitHub
1. Enable GitHub Pages on your repository. Note that if you use the Teachbooks template this is probably already done!
Once GitHub Pages is enabled and your book is published, you can view it by visiting the GitHub Pages URL for your repository. A summary can be seen under the <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-play UnderlineNav-octicon d-none d-sm-inline"> <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path></svg>`Actions`- `All workflows` - `call-deploy-book` in GitHub. It shows you a descriptive summary.
The summary also provides build error messages, which you might fix in a new commit.
2. Once your book files are pushed to your GitHub repository you can view the book. Make sure you wait for the action to finish (GitHub Desktop shows progress if its part of a pull request, VS Code shows progress with the GitHub Actions addon).
If this is not activated yet, you can do so as describe [here](../external/deploy-book-workflow/README). Here you can also find more information.
3. Viewing the Book: Once GitHub Pages is enabled and your book is published, you can view it by visiting the GitHub Pages URL for your repository. The URL will typically be in the format https://<username>.github.io/<repository-name>.
Alternatively you can find it in the settings
- Go to your GitHub repository's settings.
- Scroll down to the "GitHub Pages" section (left side-bar: pages)
- Copy the link or click on `Visit site`
<figure align="center">
<img src="figures/GitHubPages.PNG" alt="Example Image" width="650">
</figure>
````
`````
You can keep on [editing](edit_book) and checking your changes until you're satisfied and ready for a review by a colleague.