diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 7fffe30..70bcc8c 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -23,8 +23,9 @@ before_script: # This job tests if the book compiles gracefully after a new addition test-build: stage: test - only: - - main + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push" script: - pip install -r requirements.txt - jupyter-book clean book/ diff --git a/book/_toc.yml b/book/_toc.yml index 3e8dc0f..781daaa 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -6,6 +6,7 @@ parts: chapters: - file: installation-and-setup/git-setup - file: installation-and-setup/vscode-setup + - file: installation-and-setup/jupyter-book-setup - caption: Workflows chapters: - file: workflows/git-basic diff --git a/book/installation-and-setup/git-setup.md b/book/installation-and-setup/git-setup.md index dd95377..8bbf93e 100644 --- a/book/installation-and-setup/git-setup.md +++ b/book/installation-and-setup/git-setup.md @@ -8,10 +8,10 @@ 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 a command prompt, and execute the command `git`. 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). +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. 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: +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 ``` @@ -21,7 +21,7 @@ Click on `install`. The installation may take a couple of minutes. Once it's fin ## Setting up SSH-keys -When we want to visit the MUDE repositories on GitLab, we need to log in. The same holds if we want to interact with these repositories with Git from VS Code. This means that everytime we make a commit, pull, et cetera, we need to provide our password which becomes very tedious. Alternatively, we can provide GitLab with an SSH-key of our sytem, so that GitLab knows it is indeed us that are making the changes to the repository, removing the need to provide a password. +When we want to visit repositories on GitLab, 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: @@ -32,17 +32,17 @@ When we want to visit the MUDE repositories on GitLab, we need to log in. The sa 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. Keep note of this path, as we will need to visit it later on. + 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. 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: +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. Open the `id_ed25519.pub` file that we generated in step 2. Copy its contents and paste it in the 'Key' field of SSH-Keys menu. Give the key a Title and click 'Add key'. +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 + .** @@ -52,13 +52,13 @@ When we want to visit the MUDE repositories on GitLab, we need to log in. The sa ssh -vT git@gitlab.tudelft.nl - You should get a huge output, but somewhere in that output it should say something like: + 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, type in the following command for the username: +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 " " diff --git a/book/installation-and-setup/jupyter-book-setup.md b/book/installation-and-setup/jupyter-book-setup.md new file mode 100644 index 0000000..b9d7326 --- /dev/null +++ b/book/installation-and-setup/jupyter-book-setup.md @@ -0,0 +1,7 @@ +# Jupyter Book + +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. \ No newline at end of file diff --git a/book/installation-and-setup/vscode-setup.md b/book/installation-and-setup/vscode-setup.md index e1681b0..b162149 100644 --- a/book/installation-and-setup/vscode-setup.md +++ b/book/installation-and-setup/vscode-setup.md @@ -8,8 +8,49 @@ VS Code can be downloaded from [here](https://code.visualstudio.com). The instal ## Extensions -These are some very useful extensions when working on Jupyter Books: +When working with Jupyter Book (or Notebooks in general), these extensions are highly recommended: - [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) - for obvious reasons. Also includes Jupyter Notebook rendering. - [MyST-Markdown](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) - adds support for MyST markdown, including previews. -- [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) - enables validation of `.yml` files (the format of the Jupyter Book configuration files). \ No newline at end of file +- [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) - enables validation of `.yml` files (the format of the Jupyter Book configuration files). + +## Getting Anaconda to work in the VS Code terminal +```{tab} Windows +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. +``` +```{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. +``` \ No newline at end of file