diff --git a/book/_toc.yml b/book/_toc.yml index 13fe21f..6991f20 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -5,23 +5,21 @@ parts: - caption: Getting started! chapters: - file: installation-and-setup/user_types + - file: installation-and-setup/git - file: installation-and-setup/overview sections: - - file: installation-and-setup/git-setup - file: installation-and-setup/vscode-setup - file: installation-and-setup/git-setup_local - 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/git_bash_conda_vs-code.md - file: installation-and-setup/jupyter-book-setup - file: workflows/githubtemplate - file: workflows/collaboration sections: - file: workflows/milestones_issues - - file: workflows/repositories - file: workflows/branches - file: workflows/edit_book + - file: workflows/check_changes_online - file: workflows/merge_request - file: workflows/publish - caption: Features diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md index 92e1086..7f650d4 100644 --- a/book/basic-features/overview.md +++ b/book/basic-features/overview.md @@ -1,5 +1,10 @@ # Basic Jupyter Book Features +```{admonition} User types +:class: tip +This section is useful for user type 3-6. +``` + ```{warning} Under Construction! This page will provide a list of some commonly used book features which are all available in the original jupyter book package. However, this page includes best-practises on how to use them. diff --git a/book/features/custom_download.md b/book/features/custom_download.md index 1b88e2e..b683409 100644 --- a/book/features/custom_download.md +++ b/book/features/custom_download.md @@ -1,5 +1,10 @@ # Page download options +```{admonition} User types +:class: tip +This section is useful for user type 4-6. +``` + 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` diff --git a/book/features/custom_toc.md b/book/features/custom_toc.md index 005c970..c968c10 100644 --- a/book/features/custom_toc.md +++ b/book/features/custom_toc.md @@ -1,5 +1,10 @@ # Exclude parts of book from published book +```{admonition} User types +:class: tip +This section is useful for user type 3-6. +``` + A new feature is added to enable testing of all interactive features on the web server (i.e., in the draft book) while preventing students from seeing it. Pages in the draft book (`main` branch) can be manually stripped out of the table of contents when a merge request from `main` to `publish` is made using a tag `REMOVE-FROM-PUBLISH`. Pages marked with this feature are still visible in the draft book and books build from source on personal computers. The tag is applied as follows: ``` diff --git a/book/features/python_interactivity.md b/book/features/python_interactivity.md index b63d8aa..adfc5a6 100644 --- a/book/features/python_interactivity.md +++ b/book/features/python_interactivity.md @@ -1,5 +1,10 @@ # Python-enabled interactivity +```{admonition} User types +:class: tip +This section is useful for user type 5-6. +``` + In general, there are two option to include python-enabled interactivity embedded in your book: - - Using our [own sphinx-thebe extension](live_code.md) which makes code cells in your `.ipynb` book pages editable and executable by the reader! Opposed to the original sphinx-thebe extensions, our extension runs python in the reader's browser and doesn't rely on an external webserver for the python kernel. We highly recommend this extension as it allows you to use the strength of combining text/figures and code of a jupyter book with interactivity! + - Using our [own sphinx-thebe extension](./live_code.md) which makes code cells in your `.ipynb` book pages editable and executable by the reader! Opposed to the original sphinx-thebe extensions, our extension runs python in the reader's browser and doesn't rely on an external webserver for the python kernel. We highly recommend this extension as it allows you to use the strength of combining text/figures and code of a jupyter book with interactivity! - Using [JupyterLite](jupyterlite/jupyterlite.md) to create 'iframe-like' Ipython consoles / jupyterbook / jupyter lab environments in your book. As these 'iframes' are separate modules added to your page, the integration with the other content in your book is less flexible as with our sphinx-thebe extension. \ No newline at end of file diff --git a/book/installation-and-setup/anaconda.md b/book/installation-and-setup/anaconda.md index 6632de3..5af4006 100644 --- a/book/installation-and-setup/anaconda.md +++ b/book/installation-and-setup/anaconda.md @@ -1,11 +1,15 @@ -# Anaconda +# Managing code-related software: Anaconda ```{admonition} User types :class: tip -This page is useful for user type 5-6. +This page is useful for user type 5. ``` -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). +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. Unfortunately, each of these packages are themselves require a number of different packages to function properly. Do you like installing all of them? You shouldn't---but where do you get them come from? Many of those packages are packages required by only a few specific packages. These packages are called _dependencies_, and are necessary to make your Python packages function as expected. When you run install a specific package, `conda` (part of Anaconda) checks all of the dependent packages that are needed and makes sure they are also provided in the `environment` (collection of software with a specific version) that is being created. In reality, this is simply a folder on your computer with all of the `*.py` files stored in it. This _package management_ is what `conda` and `pip` are really doing when you use them to install a package. It also checks that it has a suitable _version_ of each dependency; this is why it sometime takes a long time to install a package Unfortunately, this means that as you add more packages to a particular environment, it gets more and more difficult to make sure everything works well together. Luckily, there is a practical solution: create new environments for specific projects to make sure the proper packages can function properly! + +## Installing anaconda + +You can download the installation files [here](https://www.anaconda.com/download). When installing Anaconda, keep in mind the following: @@ -22,4 +26,127 @@ Once installed, we will check to make sure you are ready to use Python. Anaconda 3. You should be running at least Python 3.11. If not, don’t worry, we will try to fix it below (but first make sure you have updated Anaconda as described above) 4. Which environment are you in? The name is between parenthesis at the bottom of your Anaconda Prompt: by default, this should be `(base)`. 5. How many other environments do you have? Execute `conda env list` to see a complete list. -6. Do you see the `*` in the list of environments? That is indicating your current active environment. Unless you have changed something, it should be `base`. And if you just installed Anaconda for the first time, this will be your only environment! \ No newline at end of file +6. Do you see the `*` in the list of environments? That is indicating your current active environment. Unless you have changed something, it should be `base`. And if you just installed Anaconda for the first time, this will be your only environment! + +## Software version control: environments + +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 influence on other environments. In that sense, it makes sense to create a new (working) environment every time you start a new project. You'll redo the next steps on this page therefor many times in the future! + +### Set-up environments + +Now we will set up your first environment. The following steps will create an Anaconda environment and install Python 3.11. Even if you already have Python 3.11, it is still good practice to create a dedicated Anaconda environment for each of your major projects such as creating a jupyter book. + +For simplicity we will call this environment `my_new_book`, but you can give it any name you like. + +1. Open the commmand line interface (see above) or continue in the same session if it is still active +2. Execute: `conda create --name my_new_book pip` (this may take several minutes) +3. Activate: `conda activate my_new_book` +
Check: you should now see your new environment displayed somewhere in the prompt between parenthesis, like this: `(my_new_book)` + +4. Additional 4th step: `pip install -r requirements.txt` (explanation in the following section) + +Now everytime you want to work on your jupyter-book, you need to activate the environment! (step 3) If you don't activate your environment, you will work in a 'wrong' working environment that might not contain all the packages you need. + +As mentioned before, python packages can be downloaded in the environments you create. Both NumPy and pandas are popular Python packages used for data manipulation and analysis. For the creation of Jupyter Books, we will use the package `jupyter-book`. More information about this package [here](jupyter-book-setup.md). + +### Import environments + +Working on larger projects (with many cool interactive features) may require you to install a lot of python packages. It can be useful to specify the required packages in a text-based file (for example `environment.yml`) and then telling `conda` to create the environment based on the contents of the file! + +Moreover, if you are joining a team that is working on complex projects, it can be useful for you to create a new environment based on use such a text-based file in order to create an up-to-date environment that will give you a flying start. The team might also provide a `requirements.txt` file which specifies all the packages you need to download in order to work on the project. Now it should also become clear why its preferable to create new environment for each project/book that you work on because they might require you to use different packages! + +Here's an example of what a `requirements.txt` file might look like. + +``` +# first list the packages you wish to download from PyPI +sympy + +# now list the packages (and the respective url) you wish to download from the GitLab package registry +--index-url https://__token__:glpat-JduurUdhDczFJzvzZN4G@gitlab.tudelft.nl/api/v4/projects/13957/packages/pypi/simple +teachbooks +--extra-index-url https://gitlab.tudelft.nl/api/v4/projects/17983/packages/pypi/simple +jupyterbook_patches ~= 0.1.4 +--extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple +sphinx-thebe ~= 0.9.9 + +# lastly any packages you wish to download directly from a Git repository +download_link_replacer @ git+https://gitlab.tudelft.nl/mude/sphinx-download-link-replacer +``` +This file needs to be manually updated by the team everytime a new package is required. It will be useful to routinely update the packages in your environment by downloading the required packages again. The packages used by sphinx-thebe or JupyterLite-Sphinx are not influenced by `requirements.txt`. + +You can do this by navigating your command line interface to the folder with `requirements.txt`: +````{tab} Windows +1. Open the folder you wish to use as your working directory in the File Explorer +2. Right-click the folder and click `Git bash here` +3. Confirm you are in the right place by inspecting the path listed in your prompt (it should typically start with be `C:\ ...` and end wit `>`) +4. You can also inspect the contents of the directory by executing `dir` + +```` +````{tab} Mac + +1. Find the folder you wish to use as your working directory +2. Right-click and select Get Info +3. Hold down the Alt (Option) key; the menu items will change\ +4. Select Copy … As Pathname +5. You can now paste this path into the Terminal after the `cd` command +6. Confirm you are in the right place by executing the command `pwd` +7. You can also inspect the contents of the directory by executing ls (that’s a lower case “L”) +```` + +Now you can install the required packages with: `pip install -r requirements.txt`. The TeachBooks team works with these `requirements.txt` files which makes this an essential step in the set-up of your environment! + +### Export environment + +If you want to create a file listing the required packages yourself, you can do it by creating a file with the following file extension: the `*.yml` file (pronounced "yah-mul"). It is a text-readable file, that stands for "Yet another Markup Language." This is one of _many_ types of files that use a particular type of text formatting to give a computer specific instructions. It is very similar to the way Markdown formatting works. + +The `environment.yml` file will look something like this: + +``` +name: MUDE +dependencies: + - python=3.11 + - numpy + - scipy + - matplotlib + - statsmodels + - pip + - conda-forge::jupyterlab + +``` +You should see that it uses a colon `:` to list the information, like name and dependencies. This will be processed by `conda` when creating the new environment. + +If you want to create an environment based on an existing `*.yml` file, you can follow these steps: + +1. You need to have the file locally on your computer (for example by cloning the git repositery that it is in) +2. Open Anaconda Prompt +3. Navigate to your working directory (where this file and `environment.yml` is located) +4. Finally, execute this command: `conda env create -f environment.yml` + +This may take several minutes because you are installing many packages at once! Keep an eye on the terminal window as this process is completed. First `conda` is collecting information about the dependencies, then it will _solve_ the environment; in other words, figure out which version of each package it should use. Once it is ready, it will present the list of packages and proceed with the "installation" (really just downloading `*.py` files and putting them in a folder on your computer) +Note that the prompt may ask you to confirm that the installation should proceed, depending on your system settings. + +Once the environment is created, we can activate it, and also check that everything was installed properly. Try `conda env export -n my_new_book` to see what was installed by "default." The list is very long, even though we only asked for a few packages! + +It is also interesting to try `conda env export --from-history` (make sure you activated it already), which shows the specific packages requested. + +### Deleting Environments + +Although the environments do not interfere with each other, you might want to delete environment you don't use. Try running the following in a Terminal or Anaconda prompt, which will list the file locations of your environment. + +`conda info --envs` + +If you have many projects, the amount of environments can take up a lot of space on your computer as one environment can get very large. It is a good idea to remove environments once you know they are no longer useful. + +To remove an environment, in your Anaconda Prompt, run: + +`conda remove --name my_new_book --all` + +You will be asked to confirm the deletion, then it may take a while to remove all of the files. To verify that the environment was removed, in your terminal window or an Anaconda Prompt, run: + +`conda info --envs` + +The environments list that displays should not show the removed environment. + +This information has been taken from the [Anaconda documentation](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#removing-an-environment). + +Now you can delete any other useless environments you have lying around on your computer! diff --git a/book/installation-and-setup/environments.md b/book/installation-and-setup/environments.md deleted file mode 100644 index 0a19194..0000000 --- a/book/installation-and-setup/environments.md +++ /dev/null @@ -1,121 +0,0 @@ -# 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 - -Now we will set up your first environment. The following steps will create an Anaconda environment and install Python 3.11. Even if you already have Python 3.11, it is still good practice to create a dedicated Anaconda environment for each of your major projects such as creating a jupyter book. Please make sure you have [upgraded Anaconda](https://docs.anaconda.com/free/anaconda/install/update-version/) (if you didn't just download it) before proceeding with these steps: - -For simplicity we will call this environment `my_new_book`, but you can give it any name you like. - -1. Open the commmand line interface (see above) or continue in the same session if it is still active -2. Execute: `conda create --name my_new_book pip` (this may take several minutes) -3. Activate: `conda activate my_new_book` -
Check: you should now see your new environment displayed somewhere in the prompt between parenthesis, like this: `(my_new_book)` - -4. Additional 4th step: `pip install -r requirements.txt` (explanation in the following section) - -Now everytime you want to work on your jupyter-book, you need to activate the environment! (step 3) If you don't activate your environment, you will work in a 'wrong' working environment that might not contain all the packages you need. - -As mentioned before, python packages can be downloaded in the environments you create. Both NumPy and pandas are popular Python packages used for data manipulation and analysis. For the creation of Jupyter Books, we will use the package `jupyter-book`. More information about this package [here](jupyter-book-setup.md). - -## Text-based files - -Working on larger projects (with many cool interactive features) may require you to install a lot of python packages. It can be useful to specify the required packages in a text-based file (for example `environment.yml`) and then telling `conda` to create the environment based on the contents of the file! - -Moreover, if you are joining a team that is working on complex projects, it can be useful for you to create a new environment based on use such a text-based file in order to create an up-to-date environment that will give you a flying start. The team might also provide a `requirements.txt` file which specifies all the packages you need to download in order to work on the project. Now it should also become clear why its preferrable to create new environment for each project/book that you work on because they might require you to use different packages! - -Here's an example of what a `requirements.txt` file might look like. - -``` -# first list the packages you wish to download from PyPI -sympy - -# now list the packages (and the respective url) you wish to download from the GitLab package registry ---index-url https://__token__:glpat-JduurUdhDczFJzvzZN4G@gitlab.tudelft.nl/api/v4/projects/13957/packages/pypi/simple -teachbooks ---extra-index-url https://gitlab.tudelft.nl/api/v4/projects/17983/packages/pypi/simple -jupyterbook_patches ~= 0.1.4 ---extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple -sphinx-thebe ~= 0.9.9 - -# lastly any packages you wish to download directly from a Git repository -download_link_replacer @ git+https://gitlab.tudelft.nl/mude/sphinx-download-link-replacer -``` -This file needs to be manually updated by the team everytime a new package is required. It will be useful to routinely update the packages in your environment by downloading the required packages again. The packages used by sphinx-thebe or JupyterLite-Sphinx are not influenced by `requirements.txt`. - -This can be done by typing the following in your terminal (in the right environment): `pip install -r requirements.txt`. - -**Note that the TeachBooks team works with these `requirements.txt` files which makes this an essential step in the set-up of your environment!** - -```{note} - -### Dependencies - -Unfortunately, each of these packages are themselves require a number of different packages to function properly. To see this, try executing the following command in your Anaconda prompt or terminal. You can also try it for `(base)`. - -`conda env export -n my_new_book` - -You should see a long list of packages. Do you remember installing all of them with `conda install` or `pip install`? You shouldn't---but where did they come from? Many of them are packages required by the packages that you _did_ specifically install. These packages are called _dependencies_, and are necessary to make your Python packages function as expected. When you run `conda install numpy`, for example, `conda` checks all of the dependent packages that are needed and makes sure they are also provided in the `environment` that is being created. In reality, this is simply a folder on your computer with all of the `*.py` files stored in it. This _package management_ is what `conda` and `pip` are really doing when you run them with an `install` command. It also checks that it has a suitable _version_ of each dependency; this is why it sometime takes a long time to install a package Unfortunately, this means that as you add more packages to a particular environment, it gets more and more difficult to make sure everything works well together. Luckily, there is a practical solution: create new environments for specific projects to make sure the proper packages can function properly! - -``` -## Create an environment from text-based file - -If you want to create a file listing the required packages yourself, you can do it by creating a file with the following file extension: the `*.yml` file (pronounced "yah-mul"). It is a text-readable file, that stands for "Yet another Markup Language." This is one of _many_ types of files that use a particular type of text formatting to give a computer specific instructions. It is very similar to the way Markdown formatting works. - -The `environment.yml` file will look something like this: - -``` -name: MUDE -dependencies: - - python=3.11 - - numpy - - scipy - - matplotlib - - statsmodels - - pip - - conda-forge::jupyterlab - -``` -You should see that it uses a colon `:` to list the information, like name and dependencies. This will be processed by `conda` when creating the new environment. - -If you want to create an environment based on an existing `*.yml` file, you can follow these steps: - -1. You need to have the file locally on your computer (for example by cloning the git repositery that it is in) -2. Open Anaconda Prompt -3. Navigate to your working directory (where this file and `environment.yml` is located) -4. Finally, execute this command: `conda env create -f environment.yml` - -This may take several minutes because you are installing many packages at once! Keep an eye on the terminal window as this process is completed. First `conda` is collecting information about the dependencies, then it will _solve_ the environment; in other words, figure out which version of each package it should use. Once it is ready, it will present the list of packages and proceed with the "installation" (really just downloading `*.py` files and putting them in a folder on your computer) -Note that the prompt may ask you to confirm that the installation should proceed, depending on your system settings. - -Once the environment is created, we can activate it, and also check that everything was installed properly. Try `conda env export -n my_new_book` to see what was installed by "default." The list is very long, even though we only asked for a few packages! - -It is also interesting to try `conda env export --from-history` (make sure you activated it already), which shows the specific packages requested. - -## Deleting Environments - -Although the environments do not interfere with each other, you might want to delete environment you don't use. Try running the following in a Terminal or Anaconda prompt, which will list the file locations of your environment. - -`conda info --envs` - -If you have many projects, the amount of environments can take up a lot of space on your computer as one environment can get very large. It is a good idea to remove environments once you know they are no longer useful. - -To remove an environment, in your Anaconda Prompt, run: - -`conda remove --name my_new_book --all` - -You will be asked to confirm the deletion, then it may take a while to remove all of the files. To verify that the environment was removed, in your terminal window or an Anaconda Prompt, run: - -`conda info --envs` - -The environments list that displays should not show the removed environment. - -This information has been taken from the [Anaconda documentation](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#removing-an-environment). - -Now you can delete any other useless environments you have lying around on your computer! diff --git a/book/installation-and-setup/git-setup.md b/book/installation-and-setup/git-setup.md deleted file mode 100644 index ce015c1..0000000 --- a/book/installation-and-setup/git-setup.md +++ /dev/null @@ -1,24 +0,0 @@ -# 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? - -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. - -## Terminology -This is a (non-exhaustive) list of terminology that will be used in GitLab. - -- Repository: a collection of files and folders, along with a history of their changes and who made them. -- Commit: a snapshot of the current state of the repository. -- Branch: a development line. -- Pushing: uploading new commits to the remote repository. \ No newline at end of file diff --git a/book/installation-and-setup/git-setup_local.md b/book/installation-and-setup/git-setup_local.md index 6c7bf48..8a463b3 100644 --- a/book/installation-and-setup/git-setup_local.md +++ b/book/installation-and-setup/git-setup_local.md @@ -1,53 +1,33 @@ -# How do I use Git locally? +# Git: GitHub Desktop / Git in VS Code ```{admonition} User types :class: tip -This page is useful for user type 4-6. +This page is useful for user type 4 and 5. ``` -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 - -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. GitHub Desktop provides an alternative to Git in VS Code, and will be described on a later stage. - -## Terminology -This is a (non-exhaustive) list of terminology that will be used in Git for local use. - -- Repository: a collection of files and folders, along with a history of their changes and who made them. -- Commit: a snapshot of the current state of the repository. -- Staging: preparation of files to be committed. During staging, we propose files to be committed. -- Branch: a development line. -- Local: on your own computer. -- Remote: on someone elses computer. -- Pushing: uploading new commits to the remote repository. -- Pulling: downloading new commits from the remote repository to your local repository. -- Tracked (files): files that Git knows about and keeps track of their history. -- Untracked (files): files that Git does not yet know about. +In this section you will learn how to install Git locally. Courses on Git usually make use of the command line interface to do run Git, 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. ## Installing Git -First, we need to install Git itself. +First, we need to install Git itself. Although this isn't strictly required when using GitHub Desktop -````{tab} Windows +````{tab} git on Windows 1. Go to [this webpage](https://git-scm.com/download/win) and download the correct version of Git for your system. 2. Execute the installer and go through it. You can leave all options to the default values, **but make sure the option "Git from the command line and also from 3rd-party software" is selected**. Without this option, we won't be able to use Git from VS Code. 3. Once the installation is finished, check if everything works. Open the start menu, then type `git`. From the search results, open the application `Git Bash`. This will open a terminal window, in which you can execute commands. Type in the command `git`, and execute it by pressing enter. If Git is installed correctly, you should see some sort of help page. If it outputs an error, then something may went wrong with the installation (you may have selected a wrong option). ```` -````{tab} MacOS +````{tab} git on MacOS Open up a terminal window (*Command + Space*, type in `terminal`). Then, type the command `git`. If Git has been installed already, it will output some help. If Git has not been installed, you will get a pop-up that looks something like this: ```{figure} ../images/install-Xcode-CLT.png ``` -Click on `install`. The installation may take a couple of minutes. Once it's finished, check if everything has been installed correctly by exectuting `git` again. +Click on `install`. The installation may take a couple of minutes. Once it's finished, check if everything has been installed correctly by executing `git` again. ```` ## Setting up SSH-keys -When we want to visit repositories on GitLab, we need to log in. The same holds if we want to interact with these repositories with Git from VS Code. This means that everytime we make a commit, pull, et cetera, we need to provide our password, which becomes very tedious. Alternatively, we can provide GitLab with an SSH-key of our sytem, so that GitLab knows it is indeed us that are making the changes to the repository, removing the need to provide a password. +When we want to visit repositories on GitLab or GitHub, we need to log in. The same holds if we want to interact with these repositories with Git from VS Code. This means that everytime we make a commit, pull, et cetera, we need to provide our password, which becomes very tedious. Alternatively, we can provide GitLab/GitHub with an SSH-key of our system, so that GitLab/GitHub knows it is indeed us that are making the changes to the repository, removing the need to provide a password. If you're only using GitHub and GitHub desktop, SSH-keys aren't strictly required, but it's still advised you set these up. 1. Open up a terminal window (Git Bash on Windows). Next, type (or copy and paste) the following command: @@ -62,6 +42,8 @@ When we want to visit repositories on GitLab, we need to log in. The same holds 3. You will now be asked to enter a passphrase. You can give one, but you will be asked for it everytime you make a commit, so it's better to leave this field emtpy and use this key only for GitLab. After the command is done executing, it will generate two files: `id_ed25519` and `id_ed25519.pub`. The `.pub` file is the public part of the SSH-Key which we need. +`````{tab-set} +````{tab-item} continue on GitLab 4. Go to [GitLab](https://gitlab.tudelft.nl) and log in using your NetID. Click on your profile icon on the top-right of the page, then go to Preferences. In the menu on the left, go to SSH-Keys. You are now greeted with a screen that looks like this: @@ -82,6 +64,41 @@ When we want to visit repositories on GitLab, we need to log in. The same holds Welcome to GitLab, ! +```` +````{tab-item} continue on GitHub + +4. Go to [GitHub](https://github.com/) and log in. In the upper-right corner of any page, click your profile photo, then click Settings. + +```{figure} https://docs.github.com/assets/cb-45016/mw-1440/images/help/settings/userbar-account-settings-global-nav-update.webp +:width: 200px +``` + +5. In the "Access" section of the sidebar, click SSH and GPG keys. + +6. Click New SSH key or Add SSH key. + +7. In the "Title" field, add a descriptive label for the new key. For example, if you're using a personal laptop, you might call this key "Personal laptop". + +8. Select the type of key: authentication + +9. Navigate to the `id_ed25519.pub` file that we generated in step 2. Open the file with a text editor (Notepad on Windows, textEdit on Mac). Copy its contents and paste it in the 'Key' field. + + ```{note} + On MacOS, the `.ssh/` folder is hidden by default, so you won't be able to find it in finder. To show hidden files and folders, press **Command + Shift + .** + ``` +10. Click Add SSH key. + +11. Now test the connection. Go to the terminal (Git Bash on windows) and type: + + ssh -vT git@github.com + + You should get a huge output, but somewhere at the end of that output it should say something like: + + Welcome to GitLab, ! + +```` +````` + ## Updating the local Git environment The final step is to provide a username and email address to Git, so our commits can be identified. To do this, in the terminal (Git Bash on Windows) type in the following command for the username: @@ -92,9 +109,23 @@ And type the following command to set the email address: git config --global user.email "" -## Configuring Git Bash +## GitHub Desktop -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}`Getting Anaconda to work in terminal `. +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](https://desktop.github.com/)! 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. GitHub Desktop provides an alternative to Git in VS Code, and will be described on a later stage. + +## Terminology +This is a (non-exhaustive) list of terminology that will be used in Git for local use. + +- Repository: a collection of files and folders, along with a history of their changes and who made them. +- Commit: a snapshot of the current state of the repository. +- Staging: preparation of files to be committed. During staging, we propose files to be committed. +- Branch: a development line. +- Local: on your own computer. +- Remote: on someone elses computer. +- Pushing: uploading new commits to the remote repository. +- Pulling: downloading new commits from the remote repository to your local repository. +- Tracked (files): files that Git knows about and keeps track of their history. +- Untracked (files): files that Git does not yet know about. ## More on GitLab diff --git a/book/installation-and-setup/git.md b/book/installation-and-setup/git.md new file mode 100644 index 0000000..09b93cb --- /dev/null +++ b/book/installation-and-setup/git.md @@ -0,0 +1,23 @@ +# Essential for collaboration: Git + +```{admonition} User types +:class: tip +This page is useful for user type 3-5. +``` + +You'll need to interact with Git to collaborate on TeachBooks, but what is that thing? + +## What is Git? + +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. + +### What is GitHub? + +GitHub is the same service as GitLab, but it's part of a commercial company (Microsoft). It's the most well-known cloud-based git provider and provides a lot of functionalities for free for education. It also allows you to host websites on `github.io` eliminating the need for your own / TU Delft webserver, although you don't have full servercontrol. + +### Additional lessons +Software carpentry offers git-lessons if you'd like to learn more than just it's specific use for TeachBooks. The lessons are available [online](https://swcarpentry.github.io/git-novice/) and TU Delft offers these as part of a [Software Carpentry workshop](https://www.tudelft.nl/library/research-data-management/r/training-evenementen/training-voor-onderzoekers/software-carpentry-workshops) \ No newline at end of file diff --git a/book/installation-and-setup/add_conda_to_path.md b/book/installation-and-setup/git_bash_conda_vs-code.md similarity index 65% rename from book/installation-and-setup/add_conda_to_path.md rename to book/installation-and-setup/git_bash_conda_vs-code.md index 6ccd00a..b11dd01 100644 --- a/book/installation-and-setup/add_conda_to_path.md +++ b/book/installation-and-setup/git_bash_conda_vs-code.md @@ -1,14 +1,16 @@ -# Getting Anaconda to work in terminal +# Combining Git Bash, VS Code and Conda ```{admonition} User types :class: tip -This page is useful for user type 5-6. +This page is useful for user type 5. ``` +## Conda in 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 here: + (vscode-setup-bash)= ````{tab} Windows - Git Bash (preferred) - -There are two things to do before you can use conda in your Git Bash CLI (possibly in VS Code): 1) adding Anaconda to your PATH variables (as user, *not* as system/admin), and 2) setting up Anaconda to run on Git Bash. +There are two things to do before you can use conda in your Git Bash CLI: 1) adding Anaconda to your PATH variables (as user, *not* as system/admin), and 2) setting up Anaconda to run on Git Bash. 1. update the `PATH` variables: * search for 'env' in the windows search to find the settings page. Anaconda doesn't recommend adding them to the system `PATH`, therefore when searching for the setting with the Windows search, so be careful to open **"edit environment variables for your account"**; do **not** "edit the system environment variables". @@ -54,4 +56,12 @@ then do the following: ```{note} This is not the preferred installation method: Powershell has a different set of terminal commands that are not Unix-based, whereas Git Bash does. Since the vast majority of coding information and examples on the internet related to Jupyter and other open source projects uses Unix-based commands, we strongly recommend you always run Git Bash for your work in the terminal. ``` -```` \ No newline at end of file +```` + +## Using Git Bash in VS Code (Windows only) +By default, Powershell is the default terminal used in VS Code. However, Git Bash is recommended because it provides Unix-like commands, making it much easier to find help on sites like Stack Exchange. It also works better with open source projects like Jupyter. Git Bash installs automatically with git which you'll learn in the next chapter; to set as default: +* Type `Ctrk+Shift+P` to open the command palette (it's also the top item in the "View" menu list) +* Start type "terminal default" and you will soon see and be able to select the setting "Terminal: Select Default Profile" (hit `Enter`) +* select Git Bash and hit "Enter" again to set as default + +When creating a new terminal via the menu bar you should now automatically start with a Git Bash terminal. Note that if a Powershell terminal still opens by default, you can always create a new terminal and manually select Git Bash. \ 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 34b3da5..9f134ea 100644 --- a/book/installation-and-setup/jupyter-book-setup.md +++ b/book/installation-and-setup/jupyter-book-setup.md @@ -1,21 +1,15 @@ -# Jupyter Book +# Build your book: JupyterBook ```{admonition} User types :class: tip -This page is useful for user type 5-6. +This page is useful for user type 5. ``` -Jupyter Book is just a regular Python package, so it can be installed by using `pip` or `conda`: - -``` -pip install jupyter-book -``` - -Nevertheless, it's always a good idea make a fresh `conda` environment when starting a new project. +Jupyter Book is a regular Python package which converts our content into a website. It's part of all of the `requirements.txt` files for a book repository. ## Build a book -As soon as you've installed jupyter-book you can build your book locally. The official [jupyter-book](https://jupyterbook.org/en/stable/basics/build.html) documentation is quite extensive. Only one note, it's advised to use `--all` whenever building a book to make sure the table of contents fully updates: +As soon as you've installed your book environment with jupyter-book you can build your book locally. The official [jupyter-book](https://jupyterbook.org/en/stable/basics/build.html) documentation is quite extensive. Only two notes: first navigate to the directory where your book is to leave out the `path-to-book` and use `--all` whenever building a book to make sure the table of contents fully updates: ``` jupyter-book build --all @@ -29,6 +23,7 @@ Once the build process is completed successfully, you will see the file location :class: tip, dropdown Bookmark the (local) file location for easy access! ``` + (setup-local-server)= ## View the book using a local webserver diff --git a/book/installation-and-setup/overview.md b/book/installation-and-setup/overview.md index 4c8e56f..3cf6b62 100644 --- a/book/installation-and-setup/overview.md +++ b/book/installation-and-setup/overview.md @@ -1,12 +1,12 @@ -# Installation for book reviewers and editors +# Install & authenticate required software + +Now that the types of users have been explained, you might have an idea which type corresponds to you! -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
| +|User Types|Required actions|
Installation
| |:---:|:---|:---| -| 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| [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) | \ No newline at end of file +| Type 1
Type 2 | Review book | No software needed! Just open your interactive book online and give review in the way you're asked to do| +| Type 3 | Edit single files online | No software needed! But you'll interact with Git, which might be a new thing for you | +| Type 4 | Editing text
Git| VS Code
GitHub Desktop / Git in VS Code | +| Type 5 | Editing text
Git
Managing code-related software
Build your book | VS Code
GitHub Desktop / Git in VS Code
Anaconda
Jupyter Book | diff --git a/book/installation-and-setup/user_types.md b/book/installation-and-setup/user_types.md index 04a5d21..4b9b0c4 100644 --- a/book/installation-and-setup/user_types.md +++ b/book/installation-and-setup/user_types.md @@ -14,18 +14,16 @@ Different types of users will interact with the website or the Jupyter Books dif 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**.
+3. **Colleague making adjustments to single files 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**.
+4. **Colleague making text adjustments to multiple files at the same time 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**.
+5. **Colleague making text and python adjustments to multiple files at the same time 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. + 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. + +
-
\ 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 5b9a074..feeea49 100644 --- a/book/installation-and-setup/vscode-setup.md +++ b/book/installation-and-setup/vscode-setup.md @@ -1,8 +1,8 @@ -# VS Code +# Editing text: VS Code ```{admonition} User types :class: tip -This page is useful for user type 4-6. +This page is useful for user type 4 and 5. ``` 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. @@ -15,15 +15,11 @@ VS Code can be downloaded from [here](https://code.visualstudio.com). The instal When working with Jupyter Book (or Notebooks in general), these extensions are highly recommended: -- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) - for obvious reasons. Also includes Jupyter Notebook rendering. -- [MyST-Markdown](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) - adds support for MyST markdown, including previews. -- [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) - enables validation of `.yml` files (the format of the Jupyter Book configuration files). - -## Using the Terminal in VS Code (Windows only) - -By default, Powershell is the default terminal used in VS Code. However, Git Bash is recommended because it provides Unix-like commands, making it much easier to find help on sites like Stack Exchange. It also works better with open source projects like Jupyter. Git Bash installs automatically with git which you'll learn in the next chapter; to set as default: -* Type `Ctrk+Shift+P` to open the command palette (it's also the top item in the "View" menu list) -* Start type "terminal default" and you will soon see and be able to select the setting "Terminal: Select Default Profile" (hit `Enter`) -* select Git Bash and hit "Enter" again to set as default - -When creating a new terminal via the menu bar you should now automatically start with a Git Bash terminal. Note that if a Powershell terminal still opens by default, you can always create a new terminal and manually select Git Bash. \ No newline at end of file +- User type 4-6: + - [MyST-Markdown](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) - adds support for MyST markdown, including previews. + - [Spell checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - Spelling checker for source code and text +- User type 5-6 + - [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) - enables validation of `.yml` files (the format of the Jupyter Book configuration files). + - [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) - for obvious reasons. Also includes Jupyter Notebook rendering. + - [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) - Your AI pair progammer + - [Jupyter Cell Tags](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.vscode-jupyter-cell-tags) - Jupyter Cell Tags support \ No newline at end of file diff --git a/book/installation-and-setup/working-directory.md b/book/installation-and-setup/working-directory.md deleted file mode 100644 index 1cc2893..0000000 --- a/book/installation-and-setup/working-directory.md +++ /dev/null @@ -1,37 +0,0 @@ -# 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. - -````{tab} Windows -1. Open the folder you wish to use as your working directory in the File Explorer -2. In the bar near the top you will see the folder address; you may need to click in the window to see the file path (i.e., the tree of folders separated by forward slashes, `/`) -3. Select the entire path and copy it (CTRL+C or right-click, “copy address as text”) -4. You can now paste this path into the Anaconda Prompt after the `cd` command -5. Confirm you are in the right place by inspecting the path listed in your prompt (it should typically start with be `C:\ ...` and end wit `>`) -6. You can also inspect the contents of the directory by executing `dir` - -Alternative -1. Open the folder you wish to use as your working directory in the File Explorer -2. Right-click the folder and click `Git bash here` -3. Confirm you are in the right place by inspecting the path listed in your prompt (it should typically start with be `C:\ ...` and end wit `>`) -4. You can also inspect the contents of the directory by executing `dir` - -```` -````{tab} Mac - -1. Find the folder you wish to use as your working directory -2. Right-click and select Get Info -3. Hold down the Alt (Option) key; the menu items will change\ -4. Select Copy … As Pathname -5. You can now paste this path into the Terminal after the `cd` command -6. Confirm you are in the right place by executing the command `pwd` -7. You can also inspect the contents of the directory by executing ls (that’s a lower case “L”) -8. Go here to see the source of this tip, along with screenshots. -```` \ No newline at end of file diff --git a/book/workflows/branches.md b/book/workflows/branches.md index d67666d..abee691 100644 --- a/book/workflows/branches.md +++ b/book/workflows/branches.md @@ -1,4 +1,4 @@ -# Branches +# Create your own version (branching, cloning, pulling) 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: @@ -9,9 +9,13 @@ 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 +`````````{tab-set} +````````{tab-item} User type 3 +**Directly create your own version (branching) or select existing version** + +`````{tab-set} +````{tab-item} 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 @@ -28,18 +32,113 @@ Click the highlighted button to make a new branch. We're making a new branch called `chapter-2` from the `main` branch. ``` -3. You should be sent back to an overview page of your repository. In the branch selection menu (see {numref}`new-branch-repo`), it should now say `chapter-2` instead of `main`. +3. You should be sent back to an overview page of your repository. In the branch selection menu (see {numref}`new-branch-repo`), it should now say `chapter-2` instead of `main`. Here you can also select another existing branch. ```{figure} ../images/gitlab-new-branch-repo.png :name: new-branch-repo The circled menu is the branch selection menu. ``` + ```` -````{tab-item} Branching in GitHub -... +````{tab-item} In GitHub + +```{error} To be written +``` ```` -````{tab-item} Branching locally with Git in VS Code +````` +```````` + +````````{tab-item} User type 4 and 5 + +```````{tab-set} +``````{tab-item} First time opening (cloning) repository + +**Find source link online repository** + +`````{tab-set} +````{tab-item} From GitLab + +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} From GitHub + +```{error} To be written +``` + +```` + +````{tab-item} From GitHub using GitHub Desktop + +```{error} To be written +``` + +```` +````` + +**Open repository locally (cloning)** + +`````{tab-set} +````{tab-item} 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} With GitHub Desktop +```{error} To be written +``` + +```` +````` + +`````` + +``````{tab-item} Using previously opened (cloned) repository + +**Obtain newest version from online repository (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. you can do so by `pull` changes from the remote repository on GitHub / GitLab into your local folder. +`````{tab-set} +````{tab-item} With Git in VS Code + +```{error} To be written +``` + +```` +````{tab-item} With GitHub Desktop + +```{error} To be written +``` + +```` +````` +`````` + +``````` +**Create your own version (branching)** + +`````{tab-set} +````{tab-item} With Git in VS Code + +```{error} To be written +``` + 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 @@ -50,12 +149,15 @@ Location of the branch menu. ```{figure} ../images/git-branch-selection-menu.png :name: git-branch-selection-menu -The branch selection menu, where our new branch has shown up. +The branch selection menu, where our new branch has shown up. From this menu you can also select (checkout in git terms) another existing branch. ``` ```` -````{tab-item} Branching locally with GitHub Desktop -... +````{tab-item} With GitHub Desktop +```{error} To be written +``` ```` ````` +```````` +````````` Now that we've created and checked out our new branch, we can start {ref}`making and committing changes `. diff --git a/book/workflows/check_changes_online.md b/book/workflows/check_changes_online.md new file mode 100644 index 0000000..72ccd51 --- /dev/null +++ b/book/workflows/check_changes_online.md @@ -0,0 +1,17 @@ +# Check changes online + +Now that you've pushed your changes online, it's time to check the change in the online build book to make sure that your changes are processed correctly. For this step it is assumed you're using TeachBook's GitHub actions or TeachBook's GitLab pipeline. + + +`````{tab-set} +````{tab-item} In GitLab +At the moment this is not possible, but the workflow will soon be the same as for GitHub. +```` +````{tab-item} In GitHub +- Wait for the action to finish +- Visit the website of your build book +```{error} To be written +``` +````` + +You can keep on [editing](edit_book) and checking your changes until you're satisfied and ready for a review by a colleague. \ No newline at end of file diff --git a/book/workflows/collaboration.md b/book/workflows/collaboration.md index dfaa646..7ca4da5 100644 --- a/book/workflows/collaboration.md +++ b/book/workflows/collaboration.md @@ -2,19 +2,77 @@ ```{admonition} User types :class: tip -This page is useful for user type 3-6. +This page is useful for user type 3, 4 and 5. ``` -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. +A jupyter book is composed out of many 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. -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 +We have previously introduced the notions of using Git in the online environment (remote) or locally. All the (text, figures, etc.) 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` or `github.com/teachbooks`. + +The steps involved are as follows: + 1. Assign task to yourself + 2. Create your own version (branching) of the book by: +```````{tab-set} +``````{tab-item} User type 3 +- directly create your own version (branching) or select existing version +`````` +``````{tab-item} User type 4 and 5 +`````{tab-set} +````{tab-item} First time opening (cloning) repository +- Find source link online repository +- Open repository locally (cloning) +- Create your own version (branching) or select existing version (checkout branch) +```` +````{tab-item} Using previously opened (cloned) repository +- Obtain newest version from online repository (pulling) +- Create your own version (branching) or select existing version (checkout branch) +````` +`````` +``````` + 3. Edit the book by: +```````{tab-set} +``````{tab-item} User type 3 +- Add or make changes to a file +- Add changes to Git-timeline (committing) +`````` +``````{tab-item} User type 4 +`````{tab-set} +````{tab-item} Brand new version (branch) +- Add or make changes to file(s) +- Select files ready to be added to Git-timeline (staging) +- Add changes to Git-timeline locally (committing) +- Add changes to GitHub/GitLab (pushing) +```` +````{tab-item} Existing version (branch) +- Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling) +- Add or make changes to file(s) +- Select files ready to be added to Git-timeline (staging) +- Add changes to Git-timeline locally (committing) +- Add changes to GitHub/GitLab (pushing) +```` +````` +`````` +``````{tab-item} User type 5 +`````{tab-set} +````{tab-item} Brand new version (branch) +- Add or make changes to file(s) +- Check changes in book locally +- Select files ready to be added to Git-timeline (staging) +- Add changes to Git-timeline locally (committing) +- Add changes to GitHub/GitLab (pushing) +```` +````{tab-item} Existing version (branch) +- Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling) +- Add or make changes to file(s) +- Check changes in book locally +- Select files ready to be added to Git-timeline (staging) +- Add changes to Git-timeline locally (committing) +- Add changes to GitHub/GitLab (pushing) +```` +````` +`````` +``````` + 4. Check changes online + 5. Repeat steps 3 and 4 until you're satisfied + 6. Reviewing (merge request), (eventually repeat steps 3 and 4) and combine (merging) your version with main draft version of book + 7. Publish changes to student version of the book (merge request) \ No newline at end of file diff --git a/book/workflows/edit_book.md b/book/workflows/edit_book.md index b6bbfda..5ef35dc 100644 --- a/book/workflows/edit_book.md +++ b/book/workflows/edit_book.md @@ -1,34 +1,101 @@ -# Editing the book +# Edit (merge conflicts, staging, committing, pushing) -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. -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!). +`````````{tab-set} +````````{tab-item} User type 3 -## Pulling +**Add or make changes to a file** -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. +Make changes to file in text editor... +or add new file by text or upload + +```{error} To be written +``` + +```````` +````````{tab-item} User type 4 and 5 + +```````{tab-set} +``````{tab-item} Brand new version (branch) + +If your branch was build from main, you've the most up-to-date version. So you can just continue with the next step. Next time you come here things might be different! +`````` +``````{tab-item} Existing version (branch) + +**Eventually solve conflicts with combining versions (merge conflicts, emerges after pulling)** + +If you collaborate with colleagues on this branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. Now your branch is up-to-date. However, this might lead into a merge conflict if you and colleagues have made incompatible changes. How to solve that? `````{tab-set} -````{tab-item} Pulling changes using Git in VS Code -... +````{tab-item} With Git in VS Code + +```{error} To be written +``` + ```` -````{tab-item} Pulling changes using GitHub Desktop -... +````{tab-item} With GitHub Desktop + +```{error} To be written +``` + ```` ````` -## Staging +`````` +``````` + +**Add or make changes to file(s)** + +```{error} To be written +``` +Make some changes in for example VS Code and save them. + + +```````` +````````` + +**Check changes in book locally** +```````{tab-set} +``````{tab-item} User type 3 and 4 +Not possible, unless you want to be a user type 5. Otherwise you'll see your changes later on online. +`````` +``````{tab-item} User type 5 +build book locally and eventually startup python server... +```{error} To be written +``` +`````` +``````` + +```````{tab-set} +``````{tab-item} User type 3 `````{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} In GitLab + +**Add changes to Git-timeline (committing)** + +click commit in single text editor ... +```{error} To be written +``` ```` -````{tab-item} Staging in GitHub -In GitHub staging doesn't exist, just edit a file and you can directly commit it. -... +````{tab-item} In GitHub + +**Add changes to Git-timeline (committing)** + +click commit in single text editor ... +```{error} To be written +``` ```` -````{tab-item} Staging using Git in VS Code + +`````` +``````{tab-item} User type 4 and 5 + + +`````{tab-set} +````{tab-item} Using Git in VS Code + +**Select 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: @@ -38,23 +105,9 @@ 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. +**Add changes to Git-timeline locally (committing)** -`````{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 @@ -62,30 +115,36 @@ Next, in the field that says "Message", write a short description of the changes The new file has been staged, and we've written a Commit Message. ``` +**Add changes to GitHub/GitLab (pushing)** + 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} Using GitHub Desktop + +**Select files ready to be added to Git-timeline (staging)** + +The staging GitHub Desktop assumes you want to stage all files. You can unselect some of them (unstaging them)... +```{error} To be written ``` + +**Add changes to Git-timeline locally (committing)** + +```{error} To be written +``` + +**Add changes to GitHub/GitLab (pushing)** + +```{error} To be written +``` + ```` -````{tab-item} Committing using GitHub Desktop -... -```` -````` \ No newline at end of file +````` +`````` +``````` \ No newline at end of file diff --git a/book/workflows/figures/Issues.PNG b/book/workflows/figures/issues_new.png similarity index 100% rename from book/workflows/figures/Issues.PNG rename to book/workflows/figures/issues_new.png diff --git a/book/workflows/githubtemplate.md b/book/workflows/githubtemplate.md index a39b6a5..caa2731 100644 --- a/book/workflows/githubtemplate.md +++ b/book/workflows/githubtemplate.md @@ -1,8 +1,8 @@ -# Your first TeachBook using template +# Your first TeachBook using the template ```{admonition} User types :class: tip -This page is useful for user type 3-6. +This page is useful for user type 3, 4 and 5. ``` 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. @@ -50,7 +50,8 @@ To learn more about how we do this, please see the [GitHub Actions documentation ```` ````{tab-item} GitLab template -Will follow +```{error} To be written +``` ```` ````` diff --git a/book/workflows/merge_request.md b/book/workflows/merge_request.md index 21c290b..80321f3 100644 --- a/book/workflows/merge_request.md +++ b/book/workflows/merge_request.md @@ -1,15 +1,15 @@ -# Reviewing and merging changes +# Reviewing and combine versions (merge / pull request, merging) -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. +Merging a branch into the main branch is also good moment to let a team-member review the content. 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. +We're finished with our chapter, and now it's time to include all of our commits in the `main` branch. However, it's good practice to first merge `main` into our branch, so that we can see if there are any merge conflicts. Assuming that those merge conflicts are solved before, we'll now continue this example with the following merge of our branch into `main`. `````{tab-set} -````{tab-item} Committing using GitLab +````{tab-item} In GitLab 1. Make sure that you've committed all your new sections and changes, and that they're pushed to the remote repository. @@ -41,7 +41,12 @@ The finished merge request. ``` ```` -````{tab-item} Committing using GitHub -... + +````{tab-item} In GitHub + +```{error} To be written +``` + ```` + ````` diff --git a/book/workflows/milestones_issues.md b/book/workflows/milestones_issues.md index 1c5bdf4..c1fb728 100644 --- a/book/workflows/milestones_issues.md +++ b/book/workflows/milestones_issues.md @@ -1,4 +1,4 @@ -# Milestones & Issues +# Assign task to yourself (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. @@ -12,19 +12,22 @@ An issue is built up of the following attributes: Every team member can create issues when they think of a task that would improve the book. `````{tab-set} -````{tab-item} Issues in GitLab +````{tab-item} In GitLab The issues in GitLab can be found on this page: -New Issue
+![issues](figures/issues_new.png) You can create an issue by clicking on the blue `New Issue` button in the top right corner. -New Issue
+![new issue](figures/New_Issue_GitLab.png) + ```` -````{tab-item} Issues in GitHub -... +````{tab-item} In GitHub + +```{error} To be written +``` ```` ````` diff --git a/book/workflows/publish.md b/book/workflows/publish.md index c6cbf25..9c29983 100644 --- a/book/workflows/publish.md +++ b/book/workflows/publish.md @@ -1,4 +1,7 @@ -# Publishing your book +# Publish to students -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 +For this step it is assumed you’re using TeachBook’s GitHub actions or TeachBook’s GitLab pipeline. + +Until now, you merged your changes to branch `main`, but you might see a branch called `publish` as well. 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 to prevent confusion. This way, you can still make frequent changes to the `main` branch. + +To publish your changes to the student version, simply repeat the next step but now from `main` to `publish` \ No newline at end of file diff --git a/book/workflows/repositories.md b/book/workflows/repositories.md deleted file mode 100644 index 44cc0d3..0000000 --- a/book/workflows/repositories.md +++ /dev/null @@ -1,51 +0,0 @@ -# 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