mirror of
https://github.com/TeachBooks/manual.git
synced 2026-11-12 22:35:51 +00:00
Last commit for today!
This commit is contained in:
Tom van Woudenberg
parent
e60a13d04a
commit
4b4425f3b7
16 changed files with 214 additions and 285 deletions
|
|
@ -5,15 +5,13 @@ 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
|
||||
|
|
|
|||
|
|
@ -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!
|
||||
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`
|
||||
<br> 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`.
|
||||
|
||||
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!
|
||||
|
||||
### 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!
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
<br> 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!
|
||||
|
|
@ -1,25 +1,11 @@
|
|||
# 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.
|
||||
|
||||
## 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
|
||||
|
||||
|
|
@ -127,8 +113,19 @@ And type the following command to set the email address:
|
|||
|
||||
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.
|
||||
|
||||
## Configuring Git Bash
|
||||
Git Bash is a shell (also referred to as "the terminal") that is automatically installed with git. It provides Unix-like commands on a Windows OS, and is recommended for working with open source projects like Jupyter (for example `pip install`, building Jupyter books, using Git Bash in VS Code, etc). To do this, `conda` needs to be setup properly; this is described in the {ref}`Getting Anaconda to work in terminal <vscode-setup-bash>`.
|
||||
## 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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,31 +1,23 @@
|
|||
# What is Git and GitLab?
|
||||
# Essential for collaboration: Git
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 3-6.
|
||||
This page is useful for user type 3-5.
|
||||
```
|
||||
|
||||
In this section you will learn how to perform basic Git actions in the online interface of GitLab.
|
||||
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?
|
||||
### 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?
|
||||
### 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.
|
||||
|
||||
## Terminology
|
||||
This is a (non-exhaustive) list of terminology that will be used in Git.
|
||||
|
||||
- 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.
|
||||
|
||||
## Additional lessons
|
||||
### 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)
|
||||
|
|
@ -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.
|
||||
```
|
||||
````
|
||||
````
|
||||
|
||||
## 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.
|
||||
|
|
@ -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 <path-to-book> --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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,13 +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! <br>
|
||||
The following table will link the relevant installation and setup steps for you.
|
||||
|
||||
|<div style="width:120px">User Types</div>|<div style="width:400px">Relevant Sections</div>|<div style="width:150px">Installation</div>|
|
||||
|User Types|Required actions|<div style="width:200px">Installation</div>|
|
||||
|:---:|:---|:---|
|
||||
| Type 1<br>Type 2 | No software needed!<br>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<br>Edit using VS Code<br>Local Git with VS Code / GitHub Desktop| [Git & GitLab](git-setup.md)<br>[VS Code](vscode-setup.md)<br>[How do I use git locally?](git-setup_local.md) |
|
||||
| Type 5 | Understanding Git & GitLab<br>Edit using VS Code<br>Local Git with VS Code / GitHub Desktop<br>Anaconda<br>Using Anaconda in terminal<br>Working with directories<br>Python Environments<br>Python package: Jupyter book | [Git & GitLab](git-setup.md)<br>[VS Code](vscode-setup.md)<br>[How do I use git locally?](git-setup_local.md)<br>[Anaconda](anaconda.md)<br>[Anaconda in terminal](add_conda_to_path.md)<br>[Working directories](working-directory.md)<br>[Environments](environments.md)<br>[Jupyter Book](jupyter-book-setup) |
|
||||
| Type 6 | Understanding Git & GitLab<br>Edit using VS Code<br>Local Git with VS Code / GitHub Desktop<br>Anaconda<br>Using Anaconda in terminal<br>Working with directories<br>Python Environments<br>Python package: Jupyter book <br> Extensions to create interactive features! | [Git & GitLab](git-setup.md)<br>[VS Code](vscode-setup.md)<br>[How do I use git locally?](git-setup_local.md)<br>[Anaconda](anaconda.md)<br>[Anaconda in terminal](add_conda_to_path.md)<br>[Working directories](working-directory.md)<br>[Environments](environments.md)<br>[Jupyter Book](jupyter-book-setup) <br> [Features](../features/overview.md) |
|
||||
|
||||
| Type 1<br>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<br>Git| VS Code<br>GitHub Desktop / Git in VS Code |
|
||||
| Type 5 | Editing text<br>Git<br>Managing code-related software<br>Build your book | VS Code<br>GitHub Desktop / Git in VS Code<br>Anaconda<br>Jupyter Book |
|
||||
|
|
@ -20,12 +20,10 @@ Different types of users will interact with the website or the Jupyter Books dif
|
|||
4. **Colleague making text adjustments to multiple files at the same time locally**. <br>
|
||||
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 multiple non-interactive content locally**. <br>
|
||||
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**. <br>
|
||||
5. **Colleague making text and python adjustments to multiple files at the same time locally**. <br>
|
||||
<img src="figures/type 5.jpg" alt="Example Image" align="left" width="120" style="margin: 10px;">
|
||||
|
||||
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.
|
||||
|
||||
<br style="clear:both;">
|
||||
|
||||
<br style="clear:both;">
|
||||
|
|
@ -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.
|
||||
|
|
@ -22,12 +22,4 @@ When working with Jupyter Book (or Notebooks in general), these extensions are h
|
|||
- [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
|
||||
|
||||
## Using the Terminal in VS Code (Windows only), user type 5-6 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.
|
||||
- [Jupyter Cell Tags](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.vscode-jupyter-cell-tags) - Jupyter Cell Tags support
|
||||
|
|
@ -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.
|
||||
````
|
||||
|
|
@ -46,7 +46,7 @@ The circled menu is the branch selection menu.
|
|||
`````
|
||||
``````
|
||||
|
||||
``````{tab-item} User type 4, 5 and 6
|
||||
``````{tab-item} User type 4 and 5
|
||||
|
||||
### Obtain newest version from online repository
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
```{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.
|
||||
```
|
||||
|
||||
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.
|
||||
|
|
@ -16,22 +16,22 @@ The steps involved are as follows:
|
|||
4. Edit the book by:
|
||||
`````{tab-set}
|
||||
````{tab-item} User type 3
|
||||
- Make changes to your file
|
||||
- Commit a changes
|
||||
- Add or make changes to a file
|
||||
- Share changes with others in Git-timeline
|
||||
````
|
||||
````{tab-item} User type 4
|
||||
- Pulling remote changes from others
|
||||
- Make changes to your file
|
||||
- Saving / Staging your changes
|
||||
- Commit a collection of changes
|
||||
- Eventually solve issues with combining versions
|
||||
- Add or make changes to a file(s)
|
||||
- Select files ready to be added to Git-Timeline
|
||||
- Share changes with others in Git-timeline
|
||||
- Pushing your changes
|
||||
````
|
||||
````{tab-item} User type 5 and 6
|
||||
- Pulling remote changes from others
|
||||
- Make changes to your file
|
||||
- Saving / Staging your changes
|
||||
- Check changes locally
|
||||
- Commit a collection of changes
|
||||
````{tab-item} User type 5
|
||||
- Eventually solve issues with combining versions
|
||||
- Add or make changes to a file(s)
|
||||
- Select files ready to be added to Git-Timeline
|
||||
- Check changes in book locally
|
||||
- Share changes with others in Git-timeline
|
||||
- If working on a repository locally: pushing your changes
|
||||
````
|
||||
`````
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
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.
|
||||
|
||||
## Make changes to your file
|
||||
## Add or make changes to a file(s)
|
||||
```````{tab-set}
|
||||
``````{tab-item} User type 3
|
||||
|
||||
|
|
@ -13,7 +13,7 @@ or add new file by text or upload
|
|||
```
|
||||
|
||||
``````
|
||||
``````{tab-item} User type 4, 5 and 6
|
||||
``````{tab-item} User type 4 and 5
|
||||
|
||||
### Eventually solve issues with combining versions
|
||||
First make sure you update your branch so that you've the most up-to-date version. If you collaborate on this branch, you get the updates from your colleagues as well. This might lead into a merge conflict. How to solve that?
|
||||
|
|
@ -64,18 +64,13 @@ The staging GitHub Desktop assumes you want to stage all files. You can unselect
|
|||
``````
|
||||
```````
|
||||
|
||||
## Review changes in book locally
|
||||
## 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 ...
|
||||
```{error} To be written
|
||||
```
|
||||
``````
|
||||
``````{tab-item} User type 6
|
||||
build book locally and startup python server...
|
||||
build book locally and eventually startup python server...
|
||||
```{error} To be written
|
||||
```
|
||||
``````
|
||||
|
|
@ -98,7 +93,9 @@ click commit in single text editor ...
|
|||
````
|
||||
|
||||
``````
|
||||
``````{tab-item} User type 4, 5 and 6
|
||||
``````{tab-item} User type 4 and 5
|
||||
|
||||
Now we're going the share our changes in the Git-timeline with a *commit* and to *push* our changes to the *remote* repository (the one that is on the TU Delft GitLab/GitHub), so that others can see our changes and interact with them.
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} Using Git in VS Code
|
||||
|
|
@ -124,23 +121,5 @@ After committing, click the 🔄 button to push our changes to the remote reposi
|
|||
|
||||
````
|
||||
`````
|
||||
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} 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
|
||||
...
|
||||
|
||||
````
|
||||
`````
|
||||
|
||||
``````
|
||||
```````
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ Find your file on GitLab/GitHub ...
|
|||
|
||||
``````
|
||||
|
||||
``````{tab-item} User type 4, 5 and 6
|
||||
``````{tab-item} User type 4 and 5
|
||||
|
||||
## Find source in online repository
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue