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

Ready for merge

Browse source
This commit is contained in:
Julie Kirsch 2024-03-02 18:31:39 +01:00
parent a5c54da8c1
commit 80d2fa6ef6
8 changed files with 37 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

BIN
book/.jupyterlite.doit.db Normal file
View file

Binary file not shown.

4
book/_toc.yml
View file

@ -8,8 +8,8 @@ parts:
sections: sections:
- file: installation-and-setup/user-types - file: installation-and-setup/user-types
- file: installation-and-setup/git-setup - file: installation-and-setup/git-setup
- file: installation-and-setup/git-lab - file: installation-and-setup/extension
- file: installation-and-setup/comments-extension - file: installation-and-setup/git-hub-desktop
- file: installation-and-setup/vscode-setup - file: installation-and-setup/vscode-setup
- file: installation-and-setup/jupyter-book-setup - file: installation-and-setup/jupyter-book-setup
- file: workflows/overview - file: workflows/overview

3
book/installation-and-setup/comments-extension.md
View file

@ -1,3 +0,0 @@
# Making comments on the website
This section will explain how to use the extension in order to make comments.

7
book/installation-and-setup/extension.md Normal file
View file

@ -0,0 +1,7 @@
# Making comments on the website
This section will explain how to use the extension in order to make comments.
Firstly, you will need to open your interactive text book in your browser. Take as example the [MUDE](https://mude.citg.tudelft.nl/book/intro.html) book.
If you look at the top right of the page, you will see three icons, an arrow, an eye and a note-pad. Clicking on the arrow will open the extension. The extension we are currently using is called Hypothesis. In order to use it you will have to make an account. Through the extension you will be able to highlight relevant sections and write notes and annotations. Comments on the content of the book can be submitted by making annotations and posting them to group called Feedback!

7
book/installation-and-setup/git-hub-desktop.md Normal file
View file

@ -0,0 +1,7 @@
# GitHub Desktop
By now you should have an idea on the purpose of git and GitLab. GitHub is a competitor company to GitLab. It provides very similar services, but they are often called different names, or have slightly different features. GitHub provides a free software that is very useful: GitHub Desktop!
While GitLab is a cloud-based version control system built around git, GitHub Desktop makes it possible to manage our git repositories locally on our computers, even though they are stored on GitLab. this is very useful for working with the jupyter-book more extensively and work on interactive features.

5
book/installation-and-setup/git-lab.md
View file

@ -1,5 +0,0 @@
# Git-Lab
on the [MUDE website](https://mude.citg.tudelft.nl/software/overview/) there is a video on how to use Git GitLab and GitHub GUI, maybe useful for user 3 and up

13
book/installation-and-setup/git-setup.md
View file

@ -1,7 +1,14 @@
# What is Git and how do I set it up # What is Git and how do I set it up
## What is Git?
## Installation Git is a version control system (VCS), used by a wide variety of engineers and software developers to work on projects in parallel together. It provides multiple benefits such as tracking changes to files, working side by side with other people, and the ability to rollback to previous versions of files without losing track of newer changes. It is a free and open sources software.
## What is GitLab?
GitLab is a cloud-based version control system built around git. It provides a lot more features such as Issues, Merge Requests, CI/CD pipelines, etc. TU Delft has a license to use GitLab on our own local webservers—this means that all of the files are stored digitally on the TU Delft campus, rather than some unkown webserver that could be physically located in an unsafe location. This is also why we have our “own” GitLab located at gitlab.tudelft.nl, rather than the “normal” GitLab at gitlab.com.
## Installing Git
First, we need to install Git itself. First, we need to install Git itself.
@ -69,3 +76,7 @@ And type the following command to set the email address:
## Configuring Git Bash ## Configuring Git Bash
Git Bash is a shell (also referred to as "the terminal") that is automatically installed with git. It provides Unix-like commands on a Windows OS, and is recommended for working with open source projects like Jupyter (for example `pip install`, building Jupyter books, using Git Bash in VS Code, etc). To do this, `conda` needs to be setup properly; this is described in the {ref}`instructions for setting up VS Code <vscode-setup-bash>`. Git Bash is a shell (also referred to as "the terminal") that is automatically installed with git. It provides Unix-like commands on a Windows OS, and is recommended for working with open source projects like Jupyter (for example `pip install`, building Jupyter books, using Git Bash in VS Code, etc). To do this, `conda` needs to be setup properly; this is described in the {ref}`instructions for setting up VS Code <vscode-setup-bash>`.
## More on GitLab
To get to know more about working in GitLab and getting familiar with its features, click [here](/jupyter-book-manual/book/workflows/overview.md) or watch this [video](https://www.youtube.com/watch?v=1SBtM3znviU&t=1s)!

19
book/installation-and-setup/user-types.md
View file

@ -1,10 +1,10 @@
# User Types # User Types
Different types of users will interact with the website or the Jupyter Books differently and will therefore need to know more or less about the workflow and GitLab. For now we will differentiate 5 types of users. Different types of users will interact with the website or the Jupyter Books differently and will therefore need to know more or less about the composition of the book. For now we will differentiate 5 types of users.
### 1. Students providing feedback on the published website ### 1. Students providing feedback on the published website
As can already be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html) an extension (hypothesis add link to features) has been added that allows students to highlight and annotate sections which they consider important. Through that extension students will also be able to leave feedback about the content or the website for the responsible teacher. As can already be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html) an extension has been added that allows students to highlight and annotate sections which they consider important. Through that extension students will also be able to leave feedback about the content or the website for the responsible teacher.
### 2. Colleague providing feedback on the draft website ### 2. Colleague providing feedback on the draft website
@ -14,25 +14,22 @@ In a similar manner, colleages and team members can leave content related commen
This type of user requires only very basic knowledge in GitLab in order to make changes to the website themselves without needing to install any software! Making adjustments using single text editor only requires the user to be able to login into GitLab and edit .md or .ipynb files. The changes can be done directly in the main or publish branch and if a new branch is needed for the changes then the set-up and merging can be taken care of by someone more familiar in GitLab. This type of user requires only very basic knowledge in GitLab in order to make changes to the website themselves without needing to install any software! Making adjustments using single text editor only requires the user to be able to login into GitLab and edit .md or .ipynb files. The changes can be done directly in the main or publish branch and if a new branch is needed for the changes then the set-up and merging can be taken care of by someone more familiar in GitLab.
(add pic?)
### 4. Colleague making adjustments to non-interactive content locally ### 4. Colleague making adjustments to non-interactive content locally
This user has more knowledge in GitLab than the previous user and can basically take care of branching and merging by themselves. They know how to work with software for editing .md and .ipynb files. The trickty part however is implementing interactive features in the book as they definetly require more knowledge on implementation and testing using a local python server or in the draft version online. This user has more knowledge in GitLab than the previous user and can basically take care of branching and merging by themselves. They know how to work with software for editing .md and .ipynb files. They can use the draft book online to view their changed in the book, or build the book locally. The tricky part however is implementing interactive features in the book as they definitely require more knowledge on implementation and testing using a local python server or in the draft version online.
### 5. Colleague making adjustments to all content locally ### 5. Colleague making adjustments to all content locally
This user has an understanding of GitLab and can independetly make changes on the website built through Jupyter Books. Moreove they have an understanding of various extensions that allows them to make the pages interactive for the student. This user has an understanding of GitLab and can independently make changes on the website built through Jupyter Books. Moreover they have an understanding of various extensions that allows them to make the pages interactive for the student.
### Summary ### Summary
Now that the types of users have been explained, you might have an idea which type corresponds to you! (Quiz to follow) Now that the types of users have been explained, you might have an idea which type corresponds to you! <br>
The following table will link the relevant installation and setup steps for you. The following table will link the relevant installation and setup steps for you.
|<div style="width:120px">User Types</div>|<div style="width:400px">Needed Software</div>|<div style="width:150px">Installation</div>| |<div style="width:120px">User Types</div>|<div style="width:400px">Needed Software</div>|<div style="width:150px">Installation</div>|
|:---:|:---|:---| |:---:|:---|:---|
| Type 1<br>Type 2 | No software needed!<br>Just open your interactive book and navigate to the extension | [Extension Tutorial](comments-extension.md) | | Type 1<br>Type 2 | No software needed!<br>Just open your interactive book and navigate to the extension | [Extension Tutorial](extension.md) |
| Type 3 | Git & GitLab | [Git](git-setup.md) | | Type 3 | Git & GitLab | [Git](git-setup.md) |
| Type 4 | GitLab<br>GitHub Desktop / VS Code<br>Plus maybe Anaconda, Python, knowledge on how to make environments?<br>Jupyter book | [Git](git-setup.md)<br>[GitHub Desktop](git-setup.md)<br>[VS Code](vscode-setup.md) | | Type 4 | Git & GitLab<br>GitHub Desktop<br>VS Code<br>Python Environments<br>Jupyter book | [Git](git-setup.md)<br>[GitHub Desktop](git-hub-desktop.md)<br>[VS Code](vscode-setup.md) |
| Type 5 | GitLab<br>GitHub Desktop / VS Code<br>Jupyter Book<br> Extensions | [Git](git-setup.md)<br>[GitHub Desktop](git-setup.md)<br>[VS Code](vscode-setup.md) <br>[Jupter Book]()<br>[Extensions](/book/features/overview.md) | | Type 5 | Git & GitLab<br>GitHub Desktop<br>VS Code<br>Jupyter Book<br> Extensions | [Git](git-setup.md)<br>[GitHub Desktop](git-hub-desktop.md)<br>[VS Code](vscode-setup.md)<br>[Jupyter Book](jupyter-book-setup)<br>[Extensions](../features/overview.md) |