diff --git a/book/_toc.yml b/book/_toc.yml index 99201ab..13fe21f 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -4,37 +4,37 @@ root: intro parts: - caption: Getting started! chapters: + - file: installation-and-setup/user_types - file: installation-and-setup/overview sections: - - file: installation-and-setup/extension - file: installation-and-setup/git-setup - file: installation-and-setup/vscode-setup - file: installation-and-setup/git-setup_local - sections: - - file: installation-and-setup/git-clone - - file: installation-and-setup/git-branch - - file: installation-and-setup/git-stage-commit-push - - file: installation-and-setup/git-merge - file: installation-and-setup/anaconda - file: installation-and-setup/add_conda_to_path - file: installation-and-setup/working-directory - file: installation-and-setup/environments - file: installation-and-setup/jupyter-book-setup - - file: workflows/overview - sections: - - file: workflows/gitlab - - file: workflows/github + - file: workflows/githubtemplate + - file: workflows/collaboration + sections: + - file: workflows/milestones_issues + - file: workflows/repositories + - file: workflows/branches + - file: workflows/edit_book + - file: workflows/merge_request + - file: workflows/publish - caption: Features chapters: - file: basic-features/overview sections: - file: basic-features/recipes.md + - file: installation-and-setup/extension - file: features/overview sections: - file: features/remove_from_publish - file: features/custom_toc.md - file: features/custom_download.md - - file: features/hypothesis - file: features/interactive_element.ipynb sections: - file: features/grasple.md diff --git a/book/features/buildbook.md b/book/features/buildbook.md new file mode 100644 index 0000000..c9acb3e --- /dev/null +++ b/book/features/buildbook.md @@ -0,0 +1,15 @@ +# Book build on webserver / GitHub Pages + +Now that we have talked about how you can collaborate using git, it's time to explain how the book is actually built. + +## GitLab Pages + +## GitHub Pages + +## Pipeline + +Both GitLab and GitHub make use of CI/CD to publish the jupyter books. CI/CD stands for Continuous Integration/Continuous Deployment. Within the scope of jupyter books focuses on automating the process of building and deploying the books. It makes sure that the book is always up-to-date and available. + +Concretely, Continuous Integration means that whenever changes are pushed to the repository (where does the publish branch come in?) the pipeline is triggered. Moreover, the pipeline also builds the book which is composed out of multiple .md or .ipynb files and converts those files into HTML. + +Continuous Deployment ensures that the book is deployed onto the desired destination (in our case the website) and accessible to the readers. \ No newline at end of file diff --git a/book/features/hypothesis.md b/book/features/hypothesis.md deleted file mode 100644 index b085d28..0000000 --- a/book/features/hypothesis.md +++ /dev/null @@ -1,19 +0,0 @@ -# Hypothesis - -Add this to `_config.yml`. Need to create an account. - - -``` -html: - comments: - hypothesis: true -``` - -```{admonition} Tips -:class: tip - -- use {ref}`remove_from_publish` to enable in Draft book only -- figure out how to use this... -``` - - diff --git a/book/images/image.png b/book/images/image.png deleted file mode 100644 index 63fd66a..0000000 Binary files a/book/images/image.png and /dev/null differ diff --git a/book/installation-and-setup/add_conda_to_path.md b/book/installation-and-setup/add_conda_to_path.md index 4c8c298..6ccd00a 100644 --- a/book/installation-and-setup/add_conda_to_path.md +++ b/book/installation-and-setup/add_conda_to_path.md @@ -1,4 +1,10 @@ # Getting Anaconda to work in terminal + +```{admonition} User types +:class: tip +This page is useful for user type 5-6. +``` + (vscode-setup-bash)= ````{tab} Windows - Git Bash (preferred) diff --git a/book/installation-and-setup/anaconda.md b/book/installation-and-setup/anaconda.md index 542f4d3..6632de3 100644 --- a/book/installation-and-setup/anaconda.md +++ b/book/installation-and-setup/anaconda.md @@ -1,5 +1,10 @@ # Anaconda +```{admonition} User types +:class: tip +This page is useful for user type 5-6. +``` + Before you can start using python in your book, you need Anaconda. 'Anaconda's conda tool simplifies package and environment management across operating systems' (Anaconda.com), such as windows or MacOS. It makes getting started with python a lot easier because it already has a lot of useful python packages pre-installed. You can download the installation files [here](https://www.anaconda.com/download). When installing Anaconda, keep in mind the following: diff --git a/book/installation-and-setup/environments.md b/book/installation-and-setup/environments.md index cb9452a..0a19194 100644 --- a/book/installation-and-setup/environments.md +++ b/book/installation-and-setup/environments.md @@ -1,5 +1,10 @@ # Creating python environments +```{admonition} User types +:class: tip +This page is useful for user type 5-6. +``` + A python virtual environment is, like the name might suggest, a reserved space within the computer that contains downloaded python packages. Each environment is like a clean slate and the packages and dependencies of one environment have no ifluence on other environments. In that sense, it makes sense to create a new (working) environment every time you start a new project. ## Set-up environments diff --git a/book/installation-and-setup/extension.md b/book/installation-and-setup/extension.md index 33cc652..dca2f8e 100644 --- a/book/installation-and-setup/extension.md +++ b/book/installation-and-setup/extension.md @@ -1,7 +1,22 @@ # Making comments on the website -This section will explain how to use the extension in order to make comments. +This section will explain how to use the extension hypothesis in order to make comments, an alternative is Utterances but this is only available for GitHub-hosted books. 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! + +## Set up hypothesis in your book +Add this to `_config.yml`. Need to create an account. + +``` +html: + comments: + hypothesis: true +``` + +```{admonition} Tips +:class: tip + +- use {ref}`remove_from_publish` to enable in Draft book only +``` \ No newline at end of file diff --git a/book/installation-and-setup/git-clone.md b/book/installation-and-setup/git-clone.md deleted file mode 100644 index 5ed959c..0000000 --- a/book/installation-and-setup/git-clone.md +++ /dev/null @@ -1,24 +0,0 @@ -(git-clone)= -# Cloning a repository - -Before we can start working on our Jupyter Book, we of course need to have the repository on our own system. This is done by *cloning* the repository, and here's how you do it with VS Code: - -1. On GitLab, go to the repository of your book. Click on the blue button that says "Clone" ({numref}`gitlab-clone`), and copy the link under "Clone with SSH". - -```{figure} ../images/gitlab-clone.png -:name: gitlab-clone - -The cloning menu. -``` - -2. Open a new VS Code window. You should be greeted with a welcome page ({numref}`vscode-welcome`). On this page, click "Clone Git Repository". Alternatively, open the Source Control menu from the left side bar, and click on "Clone Repository". - -```{figure} ../images/vscode-welcome.png -:name: vscode-welcome - -The VS Code welcome screen. -``` - -3. On the top of your screen, you should get a prompt asking you for a URL. In this field, paste the link you copied from GitLab and press enter. It will ask you to choose the location of the repository. After you've chosen a location, a final prompt will show up asking if you want to open the repository. Click on "Open". - -4. You now have a local copy of the repository. Next, {ref}`make a new branch ` for your work. \ No newline at end of file diff --git a/book/installation-and-setup/git-setup.md b/book/installation-and-setup/git-setup.md index 207ab18..ce015c1 100644 --- a/book/installation-and-setup/git-setup.md +++ b/book/installation-and-setup/git-setup.md @@ -1,5 +1,10 @@ # What is Git and GitLab? +```{admonition} User types +:class: tip +This page is useful for user type 3-6. +``` + In this section you will learn how to perform basic Git actions in the online interface of GitLab. ## What is Git? diff --git a/book/installation-and-setup/git-setup_local.md b/book/installation-and-setup/git-setup_local.md index 73502b3..6c7bf48 100644 --- a/book/installation-and-setup/git-setup_local.md +++ b/book/installation-and-setup/git-setup_local.md @@ -1,5 +1,10 @@ # How do I use Git locally? +```{admonition} User types +:class: tip +This page is useful for user type 4-6. +``` + In this section you will learn how to perform basic Git actions in VS Code / GitHub Desktop. Courses on Git usually make use of the command line interface to do these actions, but this introduces a steep learning curve. Instead, using Git from VS Code / GitHub Desktop is much more visual (i.e., more "clicky"), and therefore easier to use for those inexperienced with the command line. ## GitHub Desktop diff --git a/book/installation-and-setup/git-stage-commit-push.md b/book/installation-and-setup/git-stage-commit-push.md deleted file mode 100644 index b15f130..0000000 --- a/book/installation-and-setup/git-stage-commit-push.md +++ /dev/null @@ -1,44 +0,0 @@ -(stage-commit-push)= -# Staging, committing and pushing - -Suppose we are writing a new chapter, or are updating an existing chapter for our Jupyter Book. We've created a new branch on which we are going to make the changes, and we've checked out this branch (make sure this is really the case by checking the name of the current branch in the bottom-left corner of your VS Code window!). - -## 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: - -```{figure} ../images/git-new-file.png - -The new file appears in the Source Control menu. -``` - -Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file. - -## Committing -Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this: - -```{figure} ../images/git-file-added.png - -The new file has been staged, and we've written a Commit Message. -``` - -Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu. - -```{tip} -Unlike this example, you do not have to stage and commit every file individually. In a real case, a chapter may consist of multiple files (and images!), and it makes sense to add them in the same commit. -``` - -## Pushing the changes -Are we done now? No! Up to now, we have only made changes and committed to the *local* copy of the repository. We still need to *push* our changes to the *remote* repository (the one that is on the TU Delft GitLab), so that others can see our changes and interact with them. In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab. - -```{figure} ../images/git-push.png - -After committing, click the 🔄 button to push our changes to the remote repository. -``` - -## Summary -In short, the Git workflow consists of the following steps: - -1. Staging new and modified files -2. Writing a commit message -3. Committing the changes -4. Pushing the new changes to GitLab \ No newline at end of file diff --git a/book/installation-and-setup/jupyter-book-setup.md b/book/installation-and-setup/jupyter-book-setup.md index f2e4fd9..34b3da5 100644 --- a/book/installation-and-setup/jupyter-book-setup.md +++ b/book/installation-and-setup/jupyter-book-setup.md @@ -1,5 +1,10 @@ # Jupyter Book +```{admonition} User types +:class: tip +This page is useful for user type 5-6. +``` + Jupyter Book is just a regular Python package, so it can be installed by using `pip` or `conda`: ``` diff --git a/book/installation-and-setup/overview.md b/book/installation-and-setup/overview.md index 1c5bced..42646c3 100644 --- a/book/installation-and-setup/overview.md +++ b/book/installation-and-setup/overview.md @@ -1,25 +1,13 @@ -# Installation and setup for different 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. Example Image**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 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**. In a similar manner, colleages and team members can leave content related comments on the webiste through that extension. In this way, multiple teachers can give input in the draft of the textbook and course material without requiring and exact understanding of Jupyter Books or GitLab. The responsible teacher (or student assistants) can then make the adaptations to the book as recommended by their colleagues. -3. **Colleague making adjustments in GitLab using single text editor**. 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. - -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. 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. Example Image**Colleague making adjustments to all content locally**. 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. - -**Overview required software** +# Installation for book reviewers and editors Now that the types of users have been explained, you might have an idea which type corresponds to you!
The following table will link the relevant installation and setup steps for you. |
User Types
|
Relevant Sections
|
Installation
| |:---:|:---|:---| -| Type 1
Type 2 | No software needed!
Just open your interactive book and navigate to the extension | [Extension Tutorial](extension.md) | +| Type 1
Type 2 | No software needed!
Just open your interactive book online and give review in the way you're asked to do| | | Type 3 | Understanding Git & GitLab | [Git & GitLab](git-setup.md) | -| Type 4 | Understanding Git & GitLab
Edit using VS Code
Local Git with VS Code / GitHub Desktop
Anaconda
Using Anaconda in terminal
Working with directories
Python Environments
Python package: Jupyter book | [Git & GitLab](git-setup.md)
[VS Code](vscode-setup.md)
[How do I use git locally?](git-setup_local.md)
[Anaconda](anaconda.md)
[Anaconda in terminal](add_conda_to_path.md)
[Working directories](working-directory.md)
[Environments](environments.md)
[Jupyter Book](jupyter-book-setup) | -| Type 5 | All sections of user type 4 are also relevant for user type 5.
With the addition of using extensions to create interactive features! |[Features](../features/overview.md) | +| Type 4 | Understanding Git & GitLab
Edit using VS Code
Local Git with VS Code / GitHub Desktop| [Git & GitLab](git-setup.md)
[VS Code](vscode-setup.md)
[How do I use git locally?](git-setup_local.md) | +| Type 5 | Understanding Git & GitLab
Edit using VS Code
Local Git with VS Code / GitHub Desktop
Anaconda
Using Anaconda in terminal
Working with directories
Python Environments
Python package: Jupyter book | [Git & GitLab](git-setup.md)
[VS Code](vscode-setup.md)
[How do I use git locally?](git-setup_local.md)
[Anaconda](anaconda.md)
[Anaconda in terminal](add_conda_to_path.md)
[Working directories](working-directory.md)
[Environments](environments.md)
[Jupyter Book](jupyter-book-setup) | +| Type 6 | Understanding Git & GitLab
Edit using VS Code
Local Git with VS Code / GitHub Desktop
Anaconda
Using Anaconda in terminal
Working with directories
Python Environments
Python package: Jupyter book
Extensions to create interactive features! | [Git & GitLab](git-setup.md)
[VS Code](vscode-setup.md)
[How do I use git locally?](git-setup_local.md)
[Anaconda](anaconda.md)
[Anaconda in terminal](add_conda_to_path.md)
[Working directories](working-directory.md)
[Environments](environments.md)
[Jupyter Book](jupyter-book-setup)
[Features](../features/overview.md) | diff --git a/book/installation-and-setup/user_types.md b/book/installation-and-setup/user_types.md new file mode 100644 index 0000000..04a5d21 --- /dev/null +++ b/book/installation-and-setup/user_types.md @@ -0,0 +1,31 @@ +# 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 composition of the book. For now we will differentiate 6 types of users. + +1. **Students providing feedback on the published website**.
+Example Image + + There are multiple tools of providing feedback in the build book: + - Using the [hypothesis](https://jupyterbook.org/en/stable/interactive/comments/hypothesis.html)-extension which allows public/private highlighting and annotating parts of the book. An example can be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html) + - Using the [Utterances](https://jupyterbook.org/en/stable/interactive/comments/utterances.html)-extension which allows commenting on pages for books which are hosted on GitHub. Those comments are converted to issues on GitHub for the editors to handle. + +
+ +2. **Colleague providing feedback on the draft website**.
+ In a similar manner as students, colleages and team members can leave content related comments on the website through extensions. In this way, multiple teachers can give input in the draft of the textbook and course material without requiring and exact understanding of Jupyter Books or GitLab/GitHub. The responsible teacher (or student assistants) can then make the adaptations to the book as recommended by their colleagues. + +3. **Colleague making adjustments in GitLab/GitHub using single text editor**.
+ This type of user requires only very basic knowledge in GitLab/GitHub 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/GitHub 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/GitHub. + +4. **Colleague making text adjustments locally**.
+ User 4 is a hybrid between type 3 and 5. Basically this user is making changes by editing the .md files locally using, for example, VS Code. Therefore, this user requires a little bit more knowledge on git (think of pulling and pushing changes) but their main focus remains to make adjustments to the content of the book by editing .md files whereas user type 4 has more knowledge to make changes to python files the book as well. This user can build the book online. + +5. **Colleague making text and python adjustments to non-interactive content locally**.
+ This user has more knowledge in GitLab/GitHub 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. + +6. **Colleague making adjustments to all content locally**.
+Example Image + + This user has an understanding of GitLab/Github 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. + +
\ No newline at end of file diff --git a/book/installation-and-setup/vscode-setup.md b/book/installation-and-setup/vscode-setup.md index 155ca34..5b9a074 100644 --- a/book/installation-and-setup/vscode-setup.md +++ b/book/installation-and-setup/vscode-setup.md @@ -1,5 +1,10 @@ # VS Code +```{admonition} User types +:class: tip +This page is useful for user type 4-6. +``` + VS Code is a text editor with some extra features, such as integrated source control and a file browser. Moreover, extensions are available to add functionality to VS Code. ## Installation diff --git a/book/installation-and-setup/working-directory.md b/book/installation-and-setup/working-directory.md index b54b5ee..1cc2893 100644 --- a/book/installation-and-setup/working-directory.md +++ b/book/installation-and-setup/working-directory.md @@ -1,4 +1,10 @@ # Navigate to your working directory + +```{admonition} User types +:class: tip +This page is useful for user type 5-6. +``` + You will need to know this to set up environments from a text-based file. The essential command is `cd FILE_PATH`, which will navigate the terminal window to the directory at `FILE_PATH`. Note that although `cd` works on both Windows and Mac, many command line commands are different between the two. diff --git a/book/intro.md b/book/intro.md index f39eb56..668836f 100644 --- a/book/intro.md +++ b/book/intro.md @@ -1,6 +1,6 @@ -# Jupyter Book Manual +# TeachBooks Manual This is an introduction to Git, VS Code and Jupyter Books for teachers and teaching assistants involved in TeachBooks. This book is still work in progress, so feel free to contribute https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual! For more information about teachbooks, visit [https://teachbooks.tudelft.nl/](https://teachbooks.tudelft.nl/). ## Contact -If you encouter any issues, please contact Tom van Woudenberg, Robert Lanzafame or one of our TAs Caspar Jungbacker or Julie Kirsch at TeachBooks@tudelft.nl. +If you encounter any issues, please contact Tom van Woudenberg, Robert Lanzafame or one of our TAs Caspar Jungbacker or Julie Kirsch at TeachBooks@tudelft.nl. diff --git a/book/workflows/access_control_permissions.md b/book/workflows/access_control_permissions.md new file mode 100644 index 0000000..2aef880 --- /dev/null +++ b/book/workflows/access_control_permissions.md @@ -0,0 +1 @@ +# Access Control / Permissions \ No newline at end of file diff --git a/book/installation-and-setup/git-branch.md b/book/workflows/branches.md similarity index 75% rename from book/installation-and-setup/git-branch.md rename to book/workflows/branches.md index 0366f57..d67666d 100644 --- a/book/installation-and-setup/git-branch.md +++ b/book/workflows/branches.md @@ -1,15 +1,17 @@ -(git-branch)= # Branches -Branches are a very useful feature of Git. Branches allow you to work on multiple versions of your codebase simultaneously; you create a copy of your codebase, on which you can work independently of the main codebase. Some advantages of working with branches are: +Branches are a very useful feature of Git. Branches allow you to work on multiple versions of your codebase simultaneously; you create a copy of your codebase, on which you can work independently of the main codebase. The main branch is the default branch. The content on this branch will be the most up to date version of the book. Therefore, new branches, which are made to add or fix some content in the book, are usually cloned from the main branch. This has many advantages compared to making the edits immediately in the main branch. Some advantages of working with branches are: -- Isolation: when you work on your own branch, your changes are isolated from the main codebase. Unfinished or unreviewed parts of your book are "hidden". -- Collaboration: branches make it easier for multiple project members to work on the same codebase simultaneously. If every member works on their own branch, they can make their changes without having to worry about interfering with another members' changes. +- Isolation: when you work on your own branch, your changes are isolated from the main codebase. Unfinished or unreviewed parts of your book are "hidden". Your own branch helps to keep an overview of the changes made to the book. +- Collaboration: branches make it easier for multiple project members to work on the same codebase simultaneously. If every member works on their own branch, they can make their changes without having to worry about interfering with another members' changes. In case those changes made in parallel lead to conflicts, they can be resolved during the merging of the branches. -## How to make a branch +This systematic workflow guarantees that editing the book goes smoothly. The act of making a new branch from an existing one is called *branching*. Usually, you want to branch from the `main` branch, but you can of course also choose to branch from another branch. The branch from which you create a new branch is called the *source* branch. +`````{tab-set} +````{tab-item} Branching in GitLab + 1. On GitLab, navigate to the repository of your project. Under the project description, you should see a menu button with a "+" in it (see {numref}`new-branch-button`). Click this button, then click on "New branch". ```{figure} ../images/gitlab-branch.png @@ -33,9 +35,12 @@ We're making a new branch called `chapter-2` from the `main` branch. The circled menu is the branch selection menu. ``` - +```` +````{tab-item} Branching in GitHub +... +```` +````{tab-item} Branching locally with Git in VS Code 4. The final step is to *check out* our new branch in VS Code. *Checking out* means that we're changing our working branch (i.e., the one to which we will be committing our changes) from one to the other. In VS Code, open the branch menu from the bottom left (see {numref}`git-branch-menu-main`). You'll be be greeted with a menu that looks like the one in {numref}`git-branch-selection-menu`. In this menu, we get an overview of the branches of our repository. Notice that our new branch `chapter-2` appears as `origin/chapter-2`, and has a cloud icon in front of it. This means that the branch only exists on the remote repository. Check out the branch by simply clicking on it. Check that the branch is indeed checked out by looking at the branch menu button in the bottom left again; it should now say the name of your branch instead of `main` (in our case `chapter-2`). - ```{figure} ../images/git-branch-menu-main.png :name: git-branch-menu-main @@ -47,9 +52,10 @@ Location of the branch menu. The branch selection menu, where our new branch has shown up. ``` +```` +````{tab-item} Branching locally with GitHub Desktop +... +```` +````` -5. Now that we've created and checked out our new branch, we can start {ref}`making and committing changes `. - -## The `publish` branch - -If your repository is located in the [Interactive Textbooks CiTG](https://gitlab.tudelft.nl/interactivetextbooks-citg) group on GitLab, you will see that it already has a branch called `publish`. This branch is where the student version of your book should go. The idea behind this is that the student version of your book should only change a few times per year at most (and certainly not right before an exam!) to prevent confusion. This way, you can still make frequent changes to the `main` branch. +Now that we've created and checked out our new branch, we can start {ref}`making and committing changes `. diff --git a/book/workflows/collaboration.md b/book/workflows/collaboration.md new file mode 100644 index 0000000..dfaa646 --- /dev/null +++ b/book/workflows/collaboration.md @@ -0,0 +1,20 @@ +# Collaborative book-editing + +```{admonition} User types +:class: tip +This page is useful for user type 3-6. +``` + +As previously mentioned there are multiple platforms that can host Git repositories which are extremely useful for collaboration on text-based files. Here we will elaborate on two: GitLab and GitHub both in the online environment and locally. + +Globally, the steps involved are as follows: + 1. Define issue to work on + 2. Open the files of the repository online or clone the repository to work on it locally + 3. Create a branch for your changes + 4. Edit the book by: + - Pulling remote changes from others + - Staging your changes + - Commit a collection of changes + - If working on a repository locally: pushing your changes + 5. Reviewing and merging changes in a merge request + 6. Publish changes to published version of book \ No newline at end of file diff --git a/book/workflows/edit_book.md b/book/workflows/edit_book.md new file mode 100644 index 0000000..b6bbfda --- /dev/null +++ b/book/workflows/edit_book.md @@ -0,0 +1,91 @@ +# Editing the book + +A jupyter book is composed out of many markdown files which contain the educational content produced by you. Through the use of branches it is possible to work on the book at the same time as your team-members. Working on content for the book is mainly individual work, the beauty of git comes in when everybody's changes are merged into the main branch. + +Suppose we are writing a new chapter, or are updating an existing chapter for our Jupyter Book. We've created a new branch on which we are going to make the changes, and we've checked out this branch (make sure this is really the case by checking the name of the current branch in the bottom-left corner of your VS Code window!). + +## Pulling + +If you're working on your local version of the repository, you've to make sure you're working on the most up-to-date version of your branch, pull changes from the remote repository on GitHub / GitLab into your local folder. + +`````{tab-set} +````{tab-item} Pulling changes using Git in VS Code +... +```` +````{tab-item} Pulling changes using GitHub Desktop +... +```` +````` + +## Staging + +`````{tab-set} +````{tab-item} Staging in GitLab +In GitLab staging doesn't exist, just edit a file and you can directly commit it. +... +```` +````{tab-item} Staging in GitHub +In GitHub staging doesn't exist, just edit a file and you can directly commit it. +... +```` +````{tab-item} Staging using Git in VS Code + +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: + +```{figure} ../images/git-new-file.png + +The new file appears in the Source Control menu. +``` + +Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file. +```` +````{tab-item} Staging using GitHub Desktop +... +```` +````` + +## Committing +Now that we've made some change, we need to add them to our git-timeline. + +`````{tab-set} +````{tab-item} Committing in GitLab +... +```` +````{tab-item} Committing in GitHub +... +```` +````{tab-item} Committing using Git in VS Code +Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this: + +```{figure} ../images/git-file-added.png + +The new file has been staged, and we've written a Commit Message. +``` + +Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu. +```` +````{tab-item} Committing using GitHub Desktop +... +```` +````` + +```{tip} +Unlike this example, you do not have to stage and commit every file individually. In a real case, a chapter may consist of multiple files (and images!), and it makes sense to add them in the same commit. +``` + +## Pushing the changes +Are we done now? Yes, if you've made all your changes on GitLab / GitHub. However, no! if you did that locally! Up to now, we have only made changes and committed to the *local* copy of the repository. We still need to *push* our changes to the *remote* repository (the one that is on the TU Delft GitLab), so that others can see our changes and interact with them. + +`````{tab-set} +````{tab-item} Committing using Git in VS Code +In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab. + +```{figure} ../images/git-push.png + +After committing, click the 🔄 button to push our changes to the remote repository. +``` +```` +````{tab-item} Committing using GitHub Desktop +... +```` +````` \ No newline at end of file diff --git a/book/workflows/figures/Issues.PNG b/book/workflows/figures/Issues.PNG new file mode 100644 index 0000000..9410665 Binary files /dev/null and b/book/workflows/figures/Issues.PNG differ diff --git a/book/workflows/figures/New_Issue_GitLab.png b/book/workflows/figures/New_Issue_GitLab.png new file mode 100644 index 0000000..fb8152c Binary files /dev/null and b/book/workflows/figures/New_Issue_GitLab.png differ diff --git a/book/workflows/figures/action.png b/book/workflows/figures/action.png new file mode 100644 index 0000000..7cbb008 Binary files /dev/null and b/book/workflows/figures/action.png differ diff --git a/book/workflows/figures/create_new_repository.png b/book/workflows/figures/create_new_repository.png new file mode 100644 index 0000000..58b4e5b Binary files /dev/null and b/book/workflows/figures/create_new_repository.png differ diff --git a/book/workflows/figures/set_up_pages.png b/book/workflows/figures/set_up_pages.png new file mode 100644 index 0000000..ee2d57b Binary files /dev/null and b/book/workflows/figures/set_up_pages.png differ diff --git a/book/workflows/figures/use_github_pages_website.png b/book/workflows/figures/use_github_pages_website.png new file mode 100644 index 0000000..76a03c3 Binary files /dev/null and b/book/workflows/figures/use_github_pages_website.png differ diff --git a/book/workflows/figures/use_template.png b/book/workflows/figures/use_template.png new file mode 100644 index 0000000..c6d21fb Binary files /dev/null and b/book/workflows/figures/use_template.png differ diff --git a/book/workflows/github.md b/book/workflows/github.md deleted file mode 100644 index e8fce42..0000000 --- a/book/workflows/github.md +++ /dev/null @@ -1,58 +0,0 @@ -# Example using our GitHub template - -This page shows you how as an example how to create your own Jupyter Book. It including making an edit to a predefined book and hosting that book online. It doesn't elaborate on the collaborative functionalities of Git. - -## Setting up and first baby-editing-steps - -### Step 1: Fork book -To get started making your Jupyter Book with our functionalities, fork our template book https://github.com/TeachBooks/template : - -![alt text](../images/image.png) - -Fill in a repository name, this name will be used in the future url of your book: - -![alt text](../images/image-1.png) - -### Step 2: Setup GitHub pages with provided Actions -Set up the build of your website using GitHub pages by selecting under `Settings` - `Pages` - `Build and deployment` - `Source` - `GitHub Actions`: - -![alt text](../images/image-2.png) - -Enable the predefined workflow to publish your book under `Actions` - `I understand my workflows, go ahead an enable them`: - -![alt text](../images/image-3.png) - -### Step 3: Edit the book! -Edit a file under `Code` - `book` - A file of your choice - `Edit in place`, in the example below `book/intro.md` is edited: - -![alt text](../images/image-5.png) - -Make your edit and `Commit changes` to `main` branch: - -![alt text](../images/image-6.png) -![alt text](../images/image-7.png) - -### Step 4: Have a look at the Action -Wait a few minutes for the website to be deployed, if you're curious, have a look at the progress under `Actions` - `All workflows`: - -![alt text](../images/image-8.png) - -### Step 5: Visit published website -When the workflow has finished, visit your build book at `https://.github.io/` (case sensitive). For our example it is: [https://dummystudent-Tom.github.io/My_own_book](https://dummystudent-Tom.github.io/My_own_book) : - -![alt text](../images/image-9.png) - ---- - -It is possible to have multiple versions of a book published at once, by creating another Git branch (e.g. `draft` or `dev`). -For each branch, the respective book is published at `https://.github.io//`. -Technical note: for convenience, just `...//` redirects to `...//book/`, which is itself an alias (a symlink) for -`...//main/`. - -To learn more about how we do this, please see the [GitHub Actions documentation](https://docs.github.com/en/actions) and our deployment pipeline configuration file `.github/workflows/deploy-book-ghpages.yml` [here](https://github.com/TeachBooks/template/blob/main/.github/workflows/deploy-book-ghpages.yml). - -## Working with GitHub Desktop on this fork - -Whenever you continue working on this forked template using GitHub Desktop, make sure you select the `For my own purposes` option at `I'll be using this fork...` in the `Fork behavior` tab in `Repository settings`. This will streamline the process: - -![alt text](./figures/GitHub_desktop_fork.png) \ No newline at end of file diff --git a/book/workflows/githubtemplate.md b/book/workflows/githubtemplate.md new file mode 100644 index 0000000..a39b6a5 --- /dev/null +++ b/book/workflows/githubtemplate.md @@ -0,0 +1,57 @@ +# Your first TeachBook using template + +```{admonition} User types +:class: tip +This page is useful for user type 3-6. +``` + +This page shows you how as an example how to start your own Jupyter Book and hosting that book online. It doesn't elaborate on the collaborative functionalities of Git or how to edit the book. + +`````{tab-set} +````{tab-item} GitHub template + +1. To get started making your Jupyter Book with our functionalities, use the [template book](https://github.com/TeachBooks/template) as template: + +```{figure} figures/use_template.png +:name: use-template +``` + +2. Fill in a repository name, this name will be used in the future url of your book: + +```{figure} figures/create_new_repository.png +:name: create_new_repository +``` + +3. Set source for GitHub pages to under `Settings` - `Pages` - `Build and deployment` - `Source` - `GitHub Actions`: + +```{figure} figures/set_up_pages.png +:name: activate_pages +``` + +4. Set repository website as your GitHub Pages website under `Code`- `About` - - `Website` - `Use your GitHub Pages Website` + +```{figure} figures/use_github_pages_website.png +:name: github_pages_as_website +``` + +4. Wait a few minutes for the website to be deployed, if you're curious, have a look at the progress under `Actions` - `All workflows`: + +```{figure} figures/action.png +:name: action +``` +5. When the workflow has finished, visit your build book at `https://.github.io/` (case sensitive). For our example it is [https://dummydocent.github.io/test_book_from_template/](https://dummydocent.github.io/test_book_from_template/) for the shown repository. + +To learn more about how we do this, please see the [GitHub Actions documentation](https://docs.github.com/en/actions) and our deployment pipeline configuration file `.github/workflows/deploy-book-ghpages.yml` [here](https://github.com/TeachBooks/template/blob/main/.github/workflows/deploy-book-ghpages.yml). + +```` + +````{tab-item} GitLab template +Will follow +```` +````` + +Now that you have your book, you can continue editing your book as described in the other chapters in this book \ No newline at end of file diff --git a/book/installation-and-setup/git-merge.md b/book/workflows/merge_request.md similarity index 80% rename from book/installation-and-setup/git-merge.md rename to book/workflows/merge_request.md index 5402a75..21c290b 100644 --- a/book/installation-and-setup/git-merge.md +++ b/book/workflows/merge_request.md @@ -1,8 +1,16 @@ -(git-merge)= -# Merging +# Reviewing and merging changes + +Merging a branch into the main branch is also good moment to let a team-member review the content. This is done in the merge-request. By assigning a colleague to review your branch you can check the quality of your new content. + +```{note} +There is a slight difference in terminology between GitLab and GitHub. GitLab uses the term *Merge* Request while GitHub uses the term *Pull* Request. Both actions refer to the merging of a branch into the main branch. +``` We're finished with our chapter, and now it's time to include all of our commits in the `main` branch. +`````{tab-set} +````{tab-item} Committing using GitLab + 1. Make sure that you've committed all your new sections and changes, and that they're pushed to the remote repository. 2. Go the repository overview on GitLab. In the left menu bar, go to "Merge requests". On the Merge requests page, click "New merge request". @@ -30,4 +38,10 @@ Example of a filled-in merge request. :name: gitlab-finished-merge-request The finished merge request. -``` \ No newline at end of file +``` + +```` +````{tab-item} Committing using GitHub +... +```` +````` diff --git a/book/workflows/milestones_issues.md b/book/workflows/milestones_issues.md new file mode 100644 index 0000000..1c5bdf4 --- /dev/null +++ b/book/workflows/milestones_issues.md @@ -0,0 +1,32 @@ +# Milestones & Issues + +In a repository, team members can define Milestones and Issues. Milestones are used to track the overall progress of the project to make sure that deadlines are met. A milestone can group many issues, which are individual tasks that need to be finished in order to reach the milestone. + +An issue is built up of the following attributes: +- the title, this should just be a quick description of the task +- a label, to assign a category to the task such as: new content +- an assignee, the person who created the task can assign a team-member to the task or the task can remain without an assignee. Then whoever would like to pick up the task can assign it to themselves! +- a discussion section, here team-members can discuss any questions about the task +- a due date, in case the task is urgent or to keep track of deadlines + +Every team member can create issues when they think of a task that would improve the book. + +`````{tab-set} +````{tab-item} Issues in GitLab + +The issues in GitLab can be found on this page: + +New Issue
+ +You can create an issue by clicking on the blue `New Issue` button in the top right corner. + +New Issue
+```` + +````{tab-item} Issues in GitHub +... + +```` +````` + +When the task is completed, the issue can be closed and you can move on to the next! \ No newline at end of file diff --git a/book/workflows/overview.md b/book/workflows/overview.md deleted file mode 100644 index b202ace..0000000 --- a/book/workflows/overview.md +++ /dev/null @@ -1,7 +0,0 @@ -# Workflows - -```{warning} Under Construction! - -This page will provide a workflow how to collaborate in Git and GitLab for different uses types. Every team might have a different workflow but this workflow is shown as an example and is used in the MUDE course in CEG. - -An alternative is to use Github and Github pages to publish your book. \ No newline at end of file diff --git a/book/workflows/publish.md b/book/workflows/publish.md new file mode 100644 index 0000000..c6cbf25 --- /dev/null +++ b/book/workflows/publish.md @@ -0,0 +1,4 @@ +# Publishing your book + +Once the book is ready to be published, a static website can be created through GitLab. (Need more info on that/Are we using gitlab pages?) +If your repository is located in the [TeachBooks](https://gitlab.tudelft.nl/interactivetextbooks-citg) group on GitLab, you will see that it already has a branch called `publish`. This branch is where the student version of your book should go. The idea behind this is that the student version of your book should only change a few times per year at most (and certainly not right before an exam!) to prevent confusion. This way, you can still make frequent changes to the `main` branch. \ No newline at end of file diff --git a/book/workflows/repositories.md b/book/workflows/repositories.md new file mode 100644 index 0000000..44cc0d3 --- /dev/null +++ b/book/workflows/repositories.md @@ -0,0 +1,51 @@ +# Open files online / clone files +We have previously introduced the notions of using Git in the online environment (remote) or locally. All the (markdown) files that make up the book are contained on the remote repository on GitLab or GitHub. This could be on an open repository on `gitlab.com` or `github.com`. In the context of creating educational books for students at TU Delft, the repository will most likely be located on `gitlab.tudelft.nl`. + +If you'd like to work on your book locally, you need to clone your book. + +### Cloning a repository + +`````{tab-set} +````{tab-item} Cloning repository from GitLab + +Here's how you do it with VS Code: + +1. On GitLab, go to the repository of your book. Click on the blue button that says "Clone" ({numref}`gitlab-clone`), and copy the link under "Clone with SSH". + +```{figure} ../images/gitlab-clone.png +:name: gitlab-clone + +The cloning menu. +``` +```` + +````{tab-item} Cloning repository from GitHub +... +```` + +````{tab-item} Cloning repository from GitHub using GitHub Desktop +... +```` +````` + +Now that we've obtained the source, we can set up the files locally: + +`````{tab-set} +````{tab-item} Cloning repository with Git in VS Code +2. Open a new VS Code window. You should be greeted with a welcome page ({numref}`vscode-welcome`). On this page, click "Clone Git Repository". Alternatively, open the Source Control menu from the left side bar, and click on "Clone Repository". + +```{figure} ../images/vscode-welcome.png +:name: vscode-welcome + +The VS Code welcome screen. +``` + +3. On the top of your screen, you should get a prompt asking you for a URL. In this field, paste the link you copied from GitLab and press enter. It will ask you to choose the location of the repository. After you've chosen a location, a final prompt will show up asking if you want to open the repository. Click on "Open". + +4. You now have a local copy of the repository. +```` + +````{tab-item} Cloning repository with GitHub Desktop +.... +```` +````` \ No newline at end of file