diff --git a/book/_toc.yml b/book/_toc.yml index fcfc64f..32e6f32 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -9,6 +9,8 @@ parts: - file: installation-and-setup/extension - file: installation-and-setup/git-setup - file: installation-and-setup/git-hub-desktop + - file: installation-and-setup/anaconda + - file: installation-and-setup/working-directory - file: installation-and-setup/environments - file: installation-and-setup/vscode-setup - file: installation-and-setup/jupyter-book-setup diff --git a/book/installation-and-setup/anaconda.md b/book/installation-and-setup/anaconda.md new file mode 100644 index 0000000..f0c02e0 --- /dev/null +++ b/book/installation-and-setup/anaconda.md @@ -0,0 +1,20 @@ +# Anaconda + +However, before you can create an evironment you first need to install Anaconda. 'Anaconda's conda tool simplifies package and environment management across operating systems' (Anaconda.com), such as windows or MacOS. It makes getting started with python a lot easier because it already has a lot of useful python packages pre-installed. You can download the installation files [here](https://www.anaconda.com/download). + +When installing Anaconda, keep in mind the following: + +- In general you should use the default file location (don’t put it on a separate disk drive, or in a disk partition that is different than your primary OS); however, an exception to this is if you have a space in your Windows username (e.g., `C:/Users/First Last/Program Files`). In this case, install directly ìn a folder on `C:/` + +- install it only for your User on the computer (this is especially important on Windows; do not install for all users) + +Once installed, we will check to make sure you are ready to use Python. Anaconda provides environments, like small virtual mini-computers inside your real computer, and inside each of those environments you have Python (as well as a lot of Python packages)! + +1. Open a command line interface on your computer: +
Windows users: this will be the anaconda or conda prompt (search for it in the Start menu at the bottom left of your screen) +
Mac users: use the “terminal” application +2. Once the command line interface is open, type and execute (hit enter) the following: `python --version` +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 diff --git a/book/installation-and-setup/environments.md b/book/installation-and-setup/environments.md index d24dc3e..40dc37e 100644 --- a/book/installation-and-setup/environments.md +++ b/book/installation-and-setup/environments.md @@ -2,43 +2,52 @@ 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. -## Anaconda +## Set-up environments -However, before you can create an evironment you first need to install Anaconda. 'Anaconda's conda tool simplifies package and environment management across operating systems' (Anaconda.com), such as windows or MacOS. It makes getting started with python a lot easier because it already has a lot of useful python packages pre-installed. You can download the installation files [here](https://www.anaconda.com/download). - -When installing Anaconda, keep in mind the following: - -- In general you should use the default file location (don’t put it on a separate disk drive, or in a disk partition that is different than your primary OS); however, an exception to this is if you have a space in your Windows username (e.g., `C:/Users/First Last/Program Files`). In this case, install directly ìn a folder on `C:/` - -- install it only for your User on the computer (this is especially important on Windows; do not install for all users) - -Once installed, we will check to make sure you are ready to use Python. Anaconda provides environments, like small virtual mini-computers inside your real computer, and inside each of those environments you have Python (as well as a lot of Python packages)! - -1. Open a command line interface on your computer: -
Windows users: this will be the anaconda or conda prompt (search for it in the Start menu at the bottom left of your screen) -
Mac users: use the “terminal” application -2. Once the command line interface is open, type and execute (hit enter) the following: `python --version` -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! - -## 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/) before proceeding with these steps: +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 -n my_new_book python=3.11 anaconda` (this may take several minutes) +2. Execute: `conda create --n 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)` -Now everytime you want to work on your jupyter-book, you need to activate the environment! (step 3) +4. Additional 4th step: `pip install -r requirements.txt` (explanation in the following section) -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). +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. -## Dependencies +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. + +``` +jupyter-book +sphinx-inline-tabs +jupyterlite-xeus-python +jupyterlite-sphinx + +--extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple +sphinx-thebe == 0.2.1000 +--extra-index-url https://gitlab.tudelft.nl/api/v4/projects/17983/packages/pypi/simple +jupyterbook_patches == 0.1.2 +download_link_replacer @ git+https://gitlab.tudelft.nl/mude/sphinx-download-link-replacer@dlr-0.1.2 +``` +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. + +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)`. @@ -46,36 +55,9 @@ Unfortunately, each of these packages are themselves require a number of differe 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! -## Intermezzo: Navigate to your working directory -You will need to know this for the following steps. - -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` - -```` -````{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. -```` - +``` ## Create an environment from text-based file -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, 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. - 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: diff --git a/book/installation-and-setup/figures/type 1.jpg b/book/installation-and-setup/figures/type 1.jpg new file mode 100644 index 0000000..6abc607 Binary files /dev/null and b/book/installation-and-setup/figures/type 1.jpg differ diff --git a/book/installation-and-setup/figures/type 2.jpg b/book/installation-and-setup/figures/type 2.jpg new file mode 100644 index 0000000..e214936 Binary files /dev/null and b/book/installation-and-setup/figures/type 2.jpg differ diff --git a/book/installation-and-setup/figures/type 5.jpg b/book/installation-and-setup/figures/type 5.jpg new file mode 100644 index 0000000..f9e96dd Binary files /dev/null and b/book/installation-and-setup/figures/type 5.jpg differ diff --git a/book/installation-and-setup/overview.md b/book/installation-and-setup/overview.md index a88bfaf..b0f433a 100644 --- a/book/installation-and-setup/overview.md +++ b/book/installation-and-setup/overview.md @@ -16,9 +16,11 @@ Different types of users will interact with the website or the Jupyter Books dif 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
|
Needed Software
|
Installation
| -|:---:|:---|:---| -| Type 1
Type 2 | No software needed!
Just open your interactive book and navigate to the extension | [Extension Tutorial](extension.md) | -| Type 3 | Git & GitLab | [Git](git-setup.md) | -| Type 4 | Git & GitLab
GitHub Desktop
VS Code
Python Environments
Jupyter book | [Git](git-setup.md)
[GitHub Desktop](git-hub-desktop.md)
[VS Code](vscode-setup.md)
[Jupyter Book](jupyter-book-setup) | -| Type 5 | Git & GitLab
GitHub Desktop
VS Code
Python Environments
Jupyter Book
Extensions | [Git](git-setup.md)
[GitHub Desktop](git-hub-desktop.md)
[VS Code](vscode-setup.md)
[Jupyter Book](jupyter-book-setup)
[Extensions](../features/overview.md) | +||
User Types
|
Relevant Sections
|
Installation
| +|:---:|:---:|:---|:---| +|Example Image| Type 1
Type 2 | No software needed!
Just open your interactive book and navigate to the extension | [Extension Tutorial](extension.md) | +| | Type 3 | Understanding Git & GitLab | [Git & GitLab](git-setup.md) | +| | Type 4 | Understanding Git & GitLab
Local and remote repositeries with GitHub Desktop
Edit using VS Code
Anaconda
Working with directories
Python Environments
Python package: Jupyter book | [Git & GitLab](git-setup.md)
[GitHub Desktop](git-hub-desktop.md)
[VS Code](vscode-setup.md)
[Anaconda](anaconda.md)
[Working directories](working-directory.md)
[Environments](environments.md)
[Jupyter Book](jupyter-book-setup) | +|Example Image| Type 5 | All sections of user type 4 are also relevant for user type 5.
With the addition of using extensions to create interactive features! |[Features](../features/overview.md) | + + diff --git a/book/installation-and-setup/working-directory.md b/book/installation-and-setup/working-directory.md new file mode 100644 index 0000000..ae1a0d4 --- /dev/null +++ b/book/installation-and-setup/working-directory.md @@ -0,0 +1,25 @@ +# Navigate to your working directory +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` + +```` +````{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