diff --git a/book/_toc.yml b/book/_toc.yml index c4ba6c7..94c6153 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -8,20 +8,20 @@ parts: sections: - file: installation-and-setup/extension - file: installation-and-setup/git-setup - - file: installation-and-setup/git-hub-desktop - file: installation-and-setup/vscode-setup + - file: installation-and-setup/git-setup_local + sections: + - file: installation-and-setup/git-clone + - file: installation-and-setup/git-branch + - file: installation-and-setup/git-stage-commit-push + - file: installation-and-setup/git-merge + - file: installation-and-setup/anaconda + - file: installation-and-setup/add_conda_to_path + - file: installation-and-setup/working-directory + - file: installation-and-setup/environments - file: installation-and-setup/jupyter-book-setup - file: workflows/overview - sections: - - file: workflows/git-basic - sections: - - file: workflows/git-clone - - file: workflows/git-branch - - file: workflows/git-stage-commit-push - - file: workflows/git-merge - - file: workflows/git-advanced - sections: - - file: workflows/git-merge-conflict + sections: - file: workflows/gitlab - file: workflows/github - caption: Features diff --git a/book/features/live_code.md b/book/features/live_code.md index a8be21a..de058a9 100644 --- a/book/features/live_code.md +++ b/book/features/live_code.md @@ -15,19 +15,37 @@ This will download the correct version of the sphinx extension when the book is Afterwards, this sphinx extension needs to be enabled in your book. This can be done by adding the following lines to `_config.yml`: ``` +launch_buttons: + thebe: true + sphinx: + config: + html_js_files: + - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js + thebe_config: + use_thebe_lite: true + exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"] +``` + +The `html_js_files` link calls for some required javascript files. `use_thebe_lite` makes sure you initiate our adapted sphinx thebe extensions. The `exclude_patterns` makes sure you import all files so that they can be accessed from your code, except for the files matching the patterns shown. By `launch_buttons` you initiate the {fa}`rocket` --> {guilabel}`Live Code` on the top right corner of every page generated from a `.ipynb` file. + +Note, if you're messing around with `html_theme_options` (for example when adding more buttons), all button behaviour is affected. In that case, as opposed to the jupyter book documentation, all buttons have to be specified from within `sphinx: html_theme_options` where you might also specify other buttons as well (ie. the [code repository button](https://jupyterbook.org/en/stable/basics/repository.html)). + +``` +sphinx: + config: html_js_files: - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js thebe_config: use_thebe_lite: true exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"] html_theme_options: + repository_url: "hello!" + use_repository_button: true launch_buttons: - thebe: true + thebe: true ``` -The `html_js_files` link calls for some required javascript files. `use_thebe_lite` makes sure you initiate our adapted sphinx thebe extensions. The `exclude_patterns` makes sure you import all files so that they can be accessed from your code, except for the files matching the patterns shown. By `launch_buttons` you initiate the {fa}`rocket` --> {guilabel}`Live Code` on the top right corner of every page generated from a `.ipynb` file. As opposed to the jupyter book documentation, this button has to be specified from within `sphinx: html_theme_options` where you might also specify other buttons as well (ie. the [code repository button](https://jupyterbook.org/en/stable/basics/repository.html)). - ## Instructions: local build To test the fuctionality, you have to run a local server, otherwise the interactivity doens't work. So, you cannot just open the `index.html` file any more. This can be done with the following steps: diff --git a/book/features/overview.md b/book/features/overview.md index 181a52c..bb0cecd 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -1,4 +1,4 @@ -# CEG-book Features +# TeachBooks Features We collect a suite of existing open-source software and keep our books up-to-date so you don't have to! Some of the software is developed with our TA's to improve the learning experience of our students and ease the book-development process for our teachers. By deploying these tools from a central location we can prevent common problems before they arise, and fix them quickly when they do occur. As the open-source software landscape changes rapidly, it is esential to keep in contact and share resources amongst ourselves to minimize maintenance and downtime for our book websites and focus on what really matters: teaching! @@ -23,13 +23,3 @@ Overview of features covered: To see examples for these features, go to the Example chapter. -The {guilabel}`books-CEG` label indicates a feature developed by us. - -List: -- sphinx-thebe int {guilabel}`books-CEG` -- figure inverter -- one -- two -- free -- look at me! - diff --git a/book/features/widgets.ipynb b/book/features/widgets.ipynb index 369c08b..361cb93 100644 --- a/book/features/widgets.ipynb +++ b/book/features/widgets.ipynb @@ -6,7 +6,41 @@ "source": [ "# Widgets\n", "\n", - "If you publish widgets in a jupyter book they might (depending on your implementation) require an active python kernel for the output to be interactive. Using the [thebe-integration](live_code.md), this is possible. Note: You can circumvent the use of a kernel by using packages which don't need such a kernel, for example the [non-kernel-based widgets using Plotly](interactive_element)." + "If you publish widgets in a jupyter book they might (depending on your implementation) require an active python kernel for the output to be interactive. Using the [thebe-integration](live_code.md), this is possible. Note: You can circumvent the use of a kernel by using packages which don't need such a kernel, for example the [non-kernel-based widgets using Plotly](interactive_element).\n", + "\n", + "## `matplotlib` widgets\n", + "When you'd like to use `ipywidgets` in combinations with a `matplotlib` figure, import the following packages:\n", + "\n", + "```python\n", + "import ipywidgets as widgets\n", + "import micropip\n", + "await micropip.install(\"ipympl\")\n", + "```\n", + "\n", + "Activate the correct output format:\n", + "\n", + "```python\n", + "%matplotlib widget\n", + "```\n", + "\n", + "Write the code which generates your plot in a function:\n", + "\n", + "```python\n", + "fig = plt.figure() # Define the figure once\n", + "ax = fig.add_subplot(1,1,1) # Define the axis once\n", + "\n", + "def update_plot(input_variables_from_widget):\n", + " ax.clear() # Clear the existing plot\n", + " ax.plot(x,y) # Plot your actual data\n", + " plt.draw() # Update the plot whenever this function is executed\n", + "```\n", + "\n", + "Initiate the widget:\n", + "\n", + "```python\n", + "input_slider = widgets.FloatSlider(value=0, min=0, max=10, step=1, description='Input variable:') # Defines a widget, more options than just FloatSlider\n", + "widgets.interact(update_plot, input_variable_from_widget = input_slider);\n", + "```\n" ] }, { diff --git a/book/installation-and-setup/add_conda_to_path.md b/book/installation-and-setup/add_conda_to_path.md new file mode 100644 index 0000000..4c8c298 --- /dev/null +++ b/book/installation-and-setup/add_conda_to_path.md @@ -0,0 +1,51 @@ +# Getting Anaconda to work in terminal +(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. + +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". +* Identify the box for adding variables for a specific user (the top box), not the system. +* select the line with 'Path' and click edit +* Add the `Anaconda3` and `Anaconda3/Scripts` directories to `PATH`. + +You will know if this worked because the `conda` commands below will not produce an error. You can also check by opening a Git Bash terminal and listing your Anaconda environments with `conda env list`. + +2. To setup Anaconda, open git bash and run the collowing commands (note, the first two commands to create `myenv` can be skipped if you already have an Anaconda environment; e.g., default is `base`): +* `conda create -n myenv python` +* `conda install -n myenv numpy` +* run `conda init bash` to link conda to Git Bash +* restart shell (type `exit` to close) +* run `conda activate myenv` +* restart shell + +Check if it worked by opening a notebook in an aribtrary `DIR` using the command `jupyter lab --notebook-dir DIR`. +```` +````{tab} MacOS +Usually, Anaconda works by default in the MacOS terminal. To check if it works for you type `conda` in the termal and execute. If you get help page for `conda`, you're all set. In VS code, open a new terminal by clicking **View > Terminal** in the top menu bar. + +If you don't get a help page but something like: + + zsh: command not found: conda + +then do the following: + +1. Find out where Anaconda is installed on your system. If you left everything as default during the installation, Anaconda is installed in `/Users//anaconda3` if you used the install script, or in `/Users//opt` if you used the graphical interface to install Anaconda. + +2. Execute the following line: + + source /bin/activate + +3. Then: + + conda init zsh + +4. Restart the terminal / VS Code then test by executing `conda` again. This time, it should give you the help page. You now have access to you Anaconda environments in your command line. +```` +````{tab} Windows - Powershell + +```{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 diff --git a/book/installation-and-setup/anaconda.md b/book/installation-and-setup/anaconda.md new file mode 100644 index 0000000..542f4d3 --- /dev/null +++ b/book/installation-and-setup/anaconda.md @@ -0,0 +1,20 @@ +# Anaconda + +Before you can start using python in your book, you need Anaconda. 'Anaconda's conda tool simplifies package and environment management across operating systems' (Anaconda.com), such as windows or MacOS. It makes getting started with python a lot easier because it already has a lot of useful python packages pre-installed. You can download the installation files [here](https://www.anaconda.com/download). + +When installing Anaconda, keep in mind the following: + +- 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 new file mode 100644 index 0000000..6879fab --- /dev/null +++ b/book/installation-and-setup/environments.md @@ -0,0 +1,116 @@ +# Creating python 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 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 --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)` + +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/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/workflows/git-branch.md b/book/installation-and-setup/git-branch.md similarity index 100% rename from book/workflows/git-branch.md rename to book/installation-and-setup/git-branch.md diff --git a/book/workflows/git-clone.md b/book/installation-and-setup/git-clone.md similarity index 100% rename from book/workflows/git-clone.md rename to book/installation-and-setup/git-clone.md diff --git a/book/installation-and-setup/git-hub-desktop.md b/book/installation-and-setup/git-hub-desktop.md deleted file mode 100644 index 2f84417..0000000 --- a/book/installation-and-setup/git-hub-desktop.md +++ /dev/null @@ -1,7 +0,0 @@ -# GitHub Desktop - -By now you should have an idea on the purpose of git and GitLab. GitHub is a competitor company to GitLab. It provides very similar services, but they are often called different names, or have slightly different features. GitHub provides a free software that is very useful: GitHub Desktop! - -While GitLab is a cloud-based version control system built around git, GitHub Desktop makes it possible to manage our git repositories locally on our computers, even though they are stored on GitLab. this is very useful for working with the jupyter-book more extensively and work on interactive features. - - diff --git a/book/workflows/git-merge.md b/book/installation-and-setup/git-merge.md similarity index 100% rename from book/workflows/git-merge.md rename to book/installation-and-setup/git-merge.md diff --git a/book/installation-and-setup/git-setup.md b/book/installation-and-setup/git-setup.md index dcb16cb..207ab18 100644 --- a/book/installation-and-setup/git-setup.md +++ b/book/installation-and-setup/git-setup.md @@ -1,4 +1,6 @@ -# What is Git and how do I set it up +# What is Git and GitLab? + +In this section you will learn how to perform basic Git actions in the online interface of GitLab. ## What is Git? @@ -8,75 +10,10 @@ Git is a version control system (VCS), used by a wide variety of engineers and s GitLab is a cloud-based version control system built around git. It provides a lot more features such as Issues, Merge Requests, CI/CD pipelines, etc. TU Delft has a license to use GitLab on our own local webservers—this means that all of the files are stored digitally on the TU Delft campus, rather than some unkown webserver that could be physically located in an unsafe location. This is also why we have our “own” GitLab located at gitlab.tudelft.nl, rather than the “normal” GitLab at gitlab.com. -## Installing Git +## Terminology +This is a (non-exhaustive) list of terminology that will be used in GitLab. -First, we need to install Git itself. - -````{tab} 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 -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. -```` - -## 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. - -1. Open up a terminal window (Git Bash on Windows). Next, type (or copy and paste) the following command: - - ssh-keygen -t ed25519 -C "GitLab" - -2. You will get output that looks something like this: - - Generating public/private ed25519 key pair. - Enter file in which to save the key (/Users//.ssh/id_ed25519): - - Press enter to use the default path (the one between parenthesis). Keep note of this path, as we will need to visit it later on. - -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. - - -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: - -```{figure} ../images/gitlab-ssh-screen.png -``` - -5. 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 of SSH-Keys menu. Give the key a Title and click 'Add key'. - - ```{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 + .** - ``` - -6. Now test the connection. Go to the terminal (Git Bash on windows) and type: - - ssh -vT git@gitlab.tudelft.nl - - 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: - - git config --global user.name " " - -And type the following command to set the email address: - - git config --global user.email "" - -## Configuring Git Bash - -Git Bash is a shell (also referred to as "the terminal") that is automatically installed with git. It provides Unix-like commands on a Windows OS, and is recommended for working with open source projects like Jupyter (for example `pip install`, building Jupyter books, using Git Bash in VS Code, etc). To do this, `conda` needs to be setup properly; this is described in the {ref}`instructions for setting up VS Code `. - -## More on GitLab - -To get to know more about working in GitLab and getting familiar with its features, click [here](/jupyter-book-manual/book/workflows/overview.md) or watch this [video](https://www.youtube.com/watch?v=1SBtM3znviU&t=1s)! \ No newline at end of file +- 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 new file mode 100644 index 0000000..73502b3 --- /dev/null +++ b/book/installation-and-setup/git-setup_local.md @@ -0,0 +1,96 @@ +# How do I use Git locally? + +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. + +## Installing Git + +First, we need to install Git itself. + +````{tab} 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 +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. +```` + +## 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. + +1. Open up a terminal window (Git Bash on Windows). Next, type (or copy and paste) the following command: + + ssh-keygen -t ed25519 -C "GitLab" + +2. You will get output that looks something like this: + + Generating public/private ed25519 key pair. + Enter file in which to save the key (/Users//.ssh/id_ed25519): + + Press enter to use the default path (the one between parenthesis). Keep note of this path, as we will need to visit it later on. + +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. + + +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: + +```{figure} ../images/gitlab-ssh-screen.png +``` + +5. 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 of SSH-Keys menu. Give the key a Title and click 'Add key'. + + ```{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 + .** + ``` + +6. Now test the connection. Go to the terminal (Git Bash on windows) and type: + + ssh -vT git@gitlab.tudelft.nl + + 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: + + git config --global user.name " " + +And type the following command to set the email address: + + git config --global user.email "" + +## 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 `. + +## More on GitLab + +To get to know more about working in GitLab and getting familiar with its features, click [here](/jupyter-book-manual/book/workflows/overview.md) or watch this [video](https://www.youtube.com/watch?v=1SBtM3znviU&t=1s)! \ No newline at end of file diff --git a/book/workflows/git-stage-commit-push.md b/book/installation-and-setup/git-stage-commit-push.md similarity index 100% rename from book/workflows/git-stage-commit-push.md rename to book/installation-and-setup/git-stage-commit-push.md diff --git a/book/installation-and-setup/overview.md b/book/installation-and-setup/overview.md index a88bfaf..1c5bced 100644 --- a/book/installation-and-setup/overview.md +++ b/book/installation-and-setup/overview.md @@ -2,23 +2,24 @@ Different types of users will interact with the website or the Jupyter Books differently and will therefore need to know more or less about the composition of the book. For now we will differentiate 5 types of users. - 1. **Students providing feedback on the published website**. As can already be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html) an extension has been added that allows students to highlight and annotate sections which they consider important. Through that extension students will also be able to leave feedback about the content or the website for the responsible teacher. +1. Example Image**Students providing feedback on the published website**. As can already be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html) an extension has been added that allows students to highlight and annotate sections which they consider important. Through that extension students will also be able to leave feedback about the content or the website for the responsible teacher. 2. **Colleague providing feedback on the draft website**. In a similar manner, colleages and team members can leave content related comments on the webiste through that extension. In this way, multiple teachers can give input in the draft of the textbook and course material without requiring and exact understanding of Jupyter Books or GitLab. The responsible teacher (or student assistants) can then make the adaptations to the book as recommended by their colleagues. 3. **Colleague making adjustments in GitLab using single text editor**. This type of user requires only very basic knowledge in GitLab in order to make changes to the website themselves without needing to install any software! Making adjustments using single text editor only requires the user to be able to login into GitLab and edit .md or .ipynb files. The changes can be done directly in the main or publish branch and if a new branch is needed for the changes then the set-up and merging can be taken care of by someone more familiar in GitLab. 4. **Colleague making adjustments to non-interactive content locally**. This user has more knowledge in GitLab than the previous user and can basically take care of branching and merging by themselves. They know how to work with software for editing .md and .ipynb files. They can use the draft book online to view their changed in the book, or build the book locally. The tricky part however is implementing interactive features in the book as they definitely require more knowledge on implementation and testing using a local python server or in the draft version online. -5. **Colleague making adjustments to all content locally**. This user has an understanding of GitLab and can independently make changes on the website built through Jupyter Books. Moreover they have an understanding of various extensions that allows them to make the pages interactive for the student. +5. Example Image**Colleague making adjustments to all content locally**. This user has an understanding of GitLab and can independently make changes on the website built through Jupyter Books. Moreover they have an understanding of various extensions that allows them to make the pages interactive for the student. **Overview required software** 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
| +|
User Types
|
Relevant Sections
|
Installation
| |:---:|:---|:---| | Type 1
Type 2 | No software needed!
Just open your interactive book and navigate to the extension | [Extension Tutorial](extension.md) | -| Type 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) | +| Type 3 | Understanding Git & GitLab | [Git & GitLab](git-setup.md) | +| Type 4 | Understanding Git & GitLab
Edit using VS Code
Local Git with VS Code / GitHub Desktop
Anaconda
Using Anaconda in terminal
Working with directories
Python Environments
Python package: Jupyter book | [Git & GitLab](git-setup.md)
[VS Code](vscode-setup.md)
[How do I use git locally?](git-setup_local.md)
[Anaconda](anaconda.md)
[Anaconda in terminal](add_conda_to_path.md)
[Working directories](working-directory.md)
[Environments](environments.md)
[Jupyter Book](jupyter-book-setup) | +| Type 5 | All sections of user type 4 are also relevant for user type 5.
With the addition of using extensions to create interactive features! |[Features](../features/overview.md) | + diff --git a/book/installation-and-setup/vscode-setup.md b/book/installation-and-setup/vscode-setup.md index 446ee0f..155ca34 100644 --- a/book/installation-and-setup/vscode-setup.md +++ b/book/installation-and-setup/vscode-setup.md @@ -16,78 +16,9 @@ When working with Jupyter Book (or Notebooks in general), these extensions are h ## 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; to set as default: +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. - -## Getting Anaconda to work in the VS Code terminal -(vscode-setup-bash)= -````{tab} Windows - Git Bash (preferred) - -There are two things to do before you can use conda 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. - -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". -* Identify the box for adding variables for a specific user (the top box), not the system. -* select the line with 'Path' and click edit -* Add the `Anaconda3` and `Anaconda3/Scripts` directories to `PATH`. - -You will know if this worked because the `conda` commands below will not produce an error. You can also check by opening a Git Bash terminal and listing your Anaconda environments with `conda env list`. - -2. To setup Anaconda, open git bash and run the collowing commands (note, the first two commands to create `myenv` can be skipped if you already have an Anaconda environment; e.g., default is `base`): -* `conda create -n myenv python` -* `conda install -n myenv numpy` -* run `conda init bash` to link conda to Git Bash -* restart shell (type `exit` to close) -* run `conda activate myenv` -* restart shell - -Check if it worked by opening a notebook in an aribtrary `DIR` using the command `jupyter lab --notebook-dir DIR`. -```` -````{tab} MacOS -Usually, Anaconda works by default in the MacOS terminal. To check if it works for you, open a new terminal in VS Code by going clicking **View > Terminal** in the top menu bar. In the terminal window that appears, type `conda` and execute. If you get help page for `conda`, you're all set. If instead you get something like: - - zsh: command not found: conda - -then do the following: - -1. Find out where Anaconda is installed on your system. If you left everything as default during the installation, Anaconda is installed in `/Users//anaconda3` if you used the install script, or in `/Users//opt` if you used the graphical interface to install Anaconda. - -2. Execute the following line: - - source /bin/activate - -3. Then: - - conda init zsh - -4. Restart VS Code, then test by executing `conda` again. This time, it should give you the help page. You now have access to you Anaconda environments in the VS Code terminal. -```` -````{tab} Windows - Powershell - -```{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. -``` - -On Windows, Anaconda usually does not work in the integrated VS Code terminal (Powershell). To check if it works for you, open a new terminal in VS Code by going clicking **View > Terminal** in the top menu bar. In the terminal window that appears, type `conda` and execute. If you get help page for `conda`, you're all set. If instead you get something like: - - conda : the term 'conda' is not recognized ... - -then do the following steps: - -1. Open Anaconda prompt **as administrator**. -2. Execute the following command: - - conda init --all - -3. Close the Anaconda prompt. Then, open a Powershell window **as administrator** (go to the Start menu, type Powershell, then open Windows Powershell as administrator). -4. In the Powershell window, execute the following command: - - Set-ExecutionPolicy -ExecutionPolicy RemoteSigned - -5. The command will ask you for some permissions. To do so, type `A`, then press enter. -6. Restart VS Code, then test by executing `conda` again. This time, it should give you the help page. You now have access to you Anaconda environments in the VS Code terminal. -```` \ No newline at end of file +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/working-directory.md b/book/installation-and-setup/working-directory.md new file mode 100644 index 0000000..b54b5ee --- /dev/null +++ b/book/installation-and-setup/working-directory.md @@ -0,0 +1,31 @@ +# 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` + +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/git-advanced.md b/book/workflows/git-advanced.md deleted file mode 100644 index 9691271..0000000 --- a/book/workflows/git-advanced.md +++ /dev/null @@ -1,4 +0,0 @@ -(git-advanced)= -# Advanced Git topics - -Under construction. \ No newline at end of file diff --git a/book/workflows/git-basic.md b/book/workflows/git-basic.md deleted file mode 100644 index ccaa245..0000000 --- a/book/workflows/git-basic.md +++ /dev/null @@ -1,23 +0,0 @@ -# Working with Git in VS Code - -In this section you will learn how to perform basic Git actions in VS Code. 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 is much more visual (i.e., more "clicky"), and therefore easier to use for those inexperienced with the command line. - -## What is Git? -Git is a version control system (VCS). In short, a VCS is a tool that helps you keep track of changes to you codebase (e.g., a Jupyter Book project!) over time. It allows you to keep track of the history of changes made to your code, work collaboratively with others, and revert to a previous version of the code if needed. - -## What is GitLab? -GitLab is platform that hosts Git repositories, which can also be accessed through a web interface. Essentially, GitLab hosts the main repository that the members of a project interact with. Additionally, GitLab has plenty of other useful features such as issue tracking and code review. A selection of these features that are particularly useful for us as Jupyter Book developers will be highlighted in a {ref}`later section . - -## Terminology -This is a (non-exhaustive) list of terminology that will be used throughout this section: - -- 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. \ No newline at end of file diff --git a/book/workflows/git-merge-conflict.md b/book/workflows/git-merge-conflict.md deleted file mode 100644 index f6fa5cb..0000000 --- a/book/workflows/git-merge-conflict.md +++ /dev/null @@ -1,4 +0,0 @@ -(merge-conflicts)= -# Merge conflicts - -Under construction. \ No newline at end of file diff --git a/book/workflows/gitlab.md b/book/workflows/gitlab.md deleted file mode 100644 index 2a8bb8d..0000000 --- a/book/workflows/gitlab.md +++ /dev/null @@ -1,2 +0,0 @@ -(gitlab)= -# Useful GitLab features \ No newline at end of file