diff --git a/book/basic-features/References.md b/book/basic-features/References.md index 1a8c1ee..c2e5a27 100644 --- a/book/basic-features/References.md +++ b/book/basic-features/References.md @@ -8,7 +8,8 @@ To make references to figures, equations et cetera, use the following syntax: **Examples** -Using ``{numref}`Figure {number} ` `` produces the output: {numref}`Figure {number} `. +- Using ``{numref}`Figure {number} ` `` produces the output: {numref}`Figure {number} `. + ```{figure} ../images/git-push.png --- width: 50% @@ -17,7 +18,7 @@ name: fig-gitpush Some caption here ``` -Or, the derivation results in equation {eq}``. +- Using ``{eq}`` `` to refer to Newton's second law {eq}`eq:Newton`. $$ F = m\cdot a $$(eq:Newton) diff --git a/book/basic-features/equations.md b/book/basic-features/equations.md index 1aa80d1..e1684bd 100644 --- a/book/basic-features/equations.md +++ b/book/basic-features/equations.md @@ -1,6 +1,8 @@ # Equations -Equations can be included in two ways: inline or display mode. To make an inline equation, just put the LaTeX equation between \$-signs. For example, `$F = m \cdot a$` produces: $F = m \cdot a$. +Equations can be included in two ways: inline or display mode. + +To make an inline equation, just put the LaTeX equation between \$-signs. For example, `$F = m \cdot a$` produces: $F = m \cdot a$. Display mode equations (the ones that take up a whole line), can be inserted using double \$-signs, like this: @@ -35,9 +37,9 @@ Resulting in: $$ F = m \cdot a -$$ (newtons_second_law) +$$ (newtons_second_law_2) -Equation {eq}`newtons_second_law` can now be referred to. +Equation {eq}`newtons_second_law_2` can now be referred to. > **Note** > diff --git a/book/examples/h5p_examples.md b/book/examples/h5p_examples.md index 85ea397..bce73d9 100644 --- a/book/examples/h5p_examples.md +++ b/book/examples/h5p_examples.md @@ -5,7 +5,8 @@ This page will show some examples of H5p quizzes built into a variety of TeachBo ## Getting started with H5p Some best-practices on the use of H5p: - - To startup your H5p-account, first login to H5p via Brightspace (follow instructions as under [https://www.tudelft.nl/teaching-support/educational-tools/h5p](https://www.tudelft.nl/teaching-support/educational-tools/h5p)). After that, direct login is possible via [tudelft.h5p.com](tudelft.h5p.com) + - To startup your H5p-account, first login to H5p via Brightspace. You can follow instructions as under [https://www.tudelft.nl/teaching-support/educational-tools/h5p](https://www.tudelft.nl/teaching-support/educational-tools/h5p). + - After that, direct login is possible via [tudelft.h5p.com](https://tudelft.h5p.com) - Place your H5p-elements in a shared folder in H5p. - Disable the display options "Toolbar Below Content" and "Display author's name to public (anonymous users) (only relevant when content's status is set to Public )" for each diff --git a/book/installation-and-setup/user_types.md b/book/installation-and-setup/user_types.md index 9f99f01..df278be 100644 --- a/book/installation-and-setup/user_types.md +++ b/book/installation-and-setup/user_types.md @@ -17,8 +17,9 @@ Different types of users will interact with the website or the Jupyter Books dif 5. **Colleague making text and code (especially Python) adjustments to multiple files at the same time locally**.
Example Image
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. +
```{Note} -At this point, you might already be trying to see which user type fits you the best. We are aware that the lines between user types can be a bit blurry, especially between type 3, 4 and 5. If case you're (1) a user type 3 and want to dabble in git or (2) a user type 4/5 and want to make some quick edits with only a few clicks, then you might consider using a more advanced online editor in GitHub (GitHub Dev) as explained [further on in Collaborative book-editing - Edit - User type 3 - GitHub](../workflows/edit_book.md). +At this point, you might already be trying to see which user type fits you the best. We are aware that the lines between user types can be a bit blurry, especially between type 3, 4 and 5. In case you're (1) a user type 3 and want to dabble in git or (2) a user type 4/5 and want to make some quick edits with only a few clicks, then you might consider using a more advanced online editor in GitHub (GitHub Dev) as explained further on in [Collaborative book-editing > Edit](../workflows/edit_book.md) > User type 3 > GitHub > Using VS Code in your browser. ``` \ No newline at end of file diff --git a/book/workflows/edit_book.md b/book/workflows/edit_book.md index 99b78ea..7dd100a 100644 --- a/book/workflows/edit_book.md +++ b/book/workflows/edit_book.md @@ -4,7 +4,7 @@ Suppose we are writing a new chapter, or are updating an existing chapter for ou **Edit files as ...** `````````{tab-set} -````````{tab-item} ... user type 3 ... +````````{tab-item} ... user type 3 ... **... by directly adding changes on a single file to the Git-timeline (committing) in ...** @@ -17,39 +17,52 @@ In GitLab, you can directly make changes in the files on the remote repository. 2. Create a new file by clicking on the plus button in the top bar. You can either create an entirely new file by clicking `New File` or if you already have created a file you can upload it by clicking `Upload File`. -
- Example Image -
+```{figure} figures/User3_NewFile.PNG +width: 60% +align: center + +Create new file +``` 3. In the new window, you can start typing your content. Give your file a name and make sure to use the markdown extension: `Chapter1.md`. Once you are done, commit the new file to the repository by clicking the blue button `Commit changes`. -
- Example Image -
+```{figure} figures/User3_NewFile2.PNG +align: center + +Edit new file +``` 4. In case you want to make changes to an existing file, navigate to the file in your remote repository. Then click the blue button called `Edit` and select the option `Edit single file`. -
- Example Image -
+```{figure} figures/User3_EditFile.PNG +align: center + +Web Editor +``` 5. Make your changes in the text editor and when you are ready, commit your changes to the remote repository by clicking on the blue `Commit changes` button. -
- Example Image -
+```{figure} figures/User3_NewFile2.PNG +align: center -6. In case you added a new file, you also need to include it table of contents of your book! The table of contents is specified in a file called `toc.yml` and it is already included in your repository if you used the teachbooks template. +Commit changes +``` -
- Example Image -
+6. In case you added a new file, you also need to include it table of contents of your book! The table of contents is specified in a file called `toc.yml` and it is already included in your repository if you used the teachbooks template. You can edit it and commit the changes in the same manner as you did with markdown `file.md` files. -You can edit it and commit the changes in the same manner as with markdown (.md) files. +```{figure} figures/User3_toc.PNG +align: center + +Table of contents (TOC) +``` `````` -``````{tab-item} ... GitHub -How to make an edit and make a commit is demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial. +``````{tab-item} ... GitHub... + +`````{tab-set} +````{tab-item} ... using 'Edit in place' + +How to make an edit and make a commit is demonstrated in the gif below.
Don't worry if the steps are too fast, all steps are elaborated on in the following step-by-step tutorial. ```{figure} figures/user3-collaboration.gif --- @@ -64,84 +77,63 @@ In GitHub, you can directly make changes in the files on the remote repository. 2. Create a new file by clicking on the button called `Add file` in the top bar. You can either create an entirely new file by clicking `Create new File` or if you already have created a file you can upload it by clicking `Upload files`. -
- Example Image -
+```{figure} figures/HubUser3_NewFile.PNG +width: 80% +align: center -3. In the new window, you can start typing your content. Give your file a name and make sure to use the markdown extension: `Chapter1.md`. Once you are done, commit the new file to the repository by clicking the green button `Commit changes`. +Create new file +``` -
- Example Image -
+3. In the new window, you can start typing your content. Give your file a name and make sure to use the markdown extension: `file_name.md`. Once you are done, commit the new file to the repository by clicking the green button `Commit changes`. -`````{tab-set} -````{tab-item} ... using 'Edit in place' +```{figure} figures/HubUser3_NewFile2.PNG +width: 80% +align: center + +Edit new file +``` 4. In case you want to make changes to an existing file, navigate to the file in your remote repository. Then click the downward pointing arrow on the very left in the top bar. Select the option `Edit in place`. -
- Example Image -
+```{figure} figures/HubUser3_EditFile.PNG +width: 80% +align: center + +Edit in place +``` 5. Make your changes in the text editor and when you are ready, commit your changes to the remote repository by clicking on the green `Commit changes` button. -
- Example Image -
+```{figure} figures/HubUser3_EditFile2.PNG +width: 80% +align: center -6. In case you added a new file, you also need to include it table of contents of your book! The table of contents is specified in a file called `toc.yml` and it is already included in your repository if you used the teachbooks template. +Commit changes +``` -
- Example Image -
+6. In case you added a new file, you also need to include it table of contents of your book! The table of contents is specified in a file called `toc.yml` and it is already included in your repository if you used the teachbooks template. You can edit it and commit the changes in the same manner as with markdown `(file.md)` files. -You can edit it and commit the changes in the same manner as with markdown (.md) files. +```{figure} figures/HubUser3_toc.PNG +width: 80% +align: center +Table of contents +``` ```` + ````{tab-item} ... using 'VS Code in your browser' -Using this feature, you can open VS Code in your browser and edit the files in your repository. By doing this, you completely by-pass the need to open (and install) VS Code and GitHub Desktop on your laptop making it the optimal way to quickly fix something. +Using this feature, you can open VS Code in your browser and edit the files in your repository. By doing this, you completely by-pass the need to open (and install) VS Code and GitHub Desktop on your laptop making it the optimal way to quickly fix something. You can make changes to the files already in the repository but you can also upload new files! -1. Navigate to your main page (`code`) of your repository in GitHub -2. Press the dot key on your keyboard `.` This will open VS Code -3. Navigate to a file and make some changes - -```{figure} ./figures/Online_VS1.PNG -:name: VS Code in Browser -:width: 70% -:align: center - -VS Code in Browser +```{include} github_dev.md ``` -In the bottom left you can see the branch you are working in. - -4. This feature requires you to use git in VS Code. You can do that in the Source Control tab in the activity bar on the left side of the window (it looks like a branching icon). Write your commit message and click on commit & push. -5. Now let's see the result. Go back to your GitHub repo. In the top bar, go to actions. - -```{figure} ./figures/Online_VS2.PNG -:name: GitHub Actions -:width: 70% -:align: center - -GitHub Actions -``` -You will see the latest commit you just did (in this case text). After the pipeline has run, the yellow icon will turn green. Click on the commit and scroll until you see the title Deployed Branches. - -```{figure} ./figures/Online_VS3.PNG -:name: Deployed Branches -:width: 60% -:align: center - -Deployed Branches -``` -Click on the link and admire your changes:) ```` ````` - `````` ``````` ```````` + ````````{tab-item} ... user type 4 ... ```````{tab-set} @@ -162,36 +154,36 @@ How to make an edit and make a commit using VS Code is demonstrated in the figur name: user4_clone_edit_demo --- Demonstration, video available [here](https://youtu.be/bThimdDRXTc) +``` 1. Make some changes to a file in for example VS Code and save them. -2. Select the files ready to be added to Git-timeline (staging) +2. Select the files ready to be added to Git-timeline (staging). -For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu: + For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu: ```{figure} ../images/git-new-file.png The new file appears in the Source Control menu. ``` - -Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file. + Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file. 3. Adding changes to the Git-timeline (committing) -Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this: + Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this: ```{figure} ../images/git-file-added.png The new file has been staged, and we've written a Commit Message. ``` -Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu. + Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu. 4. 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} ... GitHub Desktop @@ -256,7 +248,7 @@ Choose one of the options to resolve the merge conflict. You now have updated yo 3. Make some further changes to a file in for example VS Code and save them. -4. Select the files ready to be added to Git-timeline (staging) +4. Select the files ready to be added to Git-timeline (staging) For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu: @@ -333,6 +325,14 @@ Alternatively, you can also click on `Push origin` in the top bar. Example Image +```` +````{tab-item} ... using 'VS Code in your browser' + +Using this feature, you can open VS Code in your browser and edit the files in your repository. This can be really useful for **quick fixes** when you dont want to launch GitHub Dekstop or VS Code. However, we would recommend to limit the use of this feature to quick changes as the other workflows allow for more complex tasks. + +```{include} github_dev.md +``` + ```` ````` `````` @@ -345,7 +345,7 @@ Alternatively, you can also click on `Push origin` in the top bar. ``````{tab-item} ... for brand new version (branch) **... by (a) making changes on a single or multiple file(s)
- (b) checking changes locally,
+ (b) checking changes locally
(c) selecting changes to be added to the Git-timeline (staging)
(d) adding changes to the Git-timeline (committing) and
(e) adding changes to GitLab/GitHub (pushing) with ...** @@ -364,37 +364,40 @@ Demonstration, video available [here](https://youtu.be/2ttjBevkEP8) 1. Make some changes to a file in for example VS Code and save them. -2. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy! +2. Once all the changes are made, it can be useful to check the changes locally on your device.
+ + By doing that you can preview how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy. -Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar. + Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar. + You will firstly need to activate the right environment. Type the following command: -You will firstly need to activate the right environment. Type the following command: +``` +conda activate jupyter-book-env +``` -`conda activate jupyter-book-env` - -(or the environment in which you have installed the TeachBooks package) - -Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command: + (or the environment in which you have installed the `teachbooks` package!) + + Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command: ``` teachbooks build ``` -Alternatively: + Alternatively: ``` jupyter-book build --all ``` -Note: use `--all` for the jupyter-book whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book. + Note: use `--all` for the jupyter-book whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book. -Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following: + Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following: -```{figure} ../figures/buildbook.PNG +```{figure} figures/buildbook.PNG Output ``` -Paste the last line into your browser to see the updated changes. + Paste the last line into your browser to see the updated changes. ```{Note} @@ -404,32 +407,32 @@ Sometimes there are problems building the book. It could be that the building re ``` -If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server] + If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server] 3. If you are satisfied with your changes, you can select the files ready to be added to Git-timeline (staging) -For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu: + For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu: ```{figure} ../images/git-new-file.png The new file appears in the Source Control menu. ``` -Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file. + Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file. 4. Adding changes to the Git-timeline (committing) -Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this: + Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this: ```{figure} ../images/git-file-added.png The new file has been staged, and we've written a Commit Message. ``` -Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu. + Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu. 5. Adding changes to GitLab/GitHub (pushing) -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/GitHub. + 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/GitHub. ```{figure} ../images/git-push.png @@ -438,39 +441,42 @@ After committing, click the 🔄 button to push our changes to the remote reposi ````{tab-item} ... GitHub Desktop -1.. Make some changes to a file in for example VS Code and save them. +1. Make some changes to a file in for example VS Code and save them. -2. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy! +2. Once all the changes are made, it can be useful to check the changes locally on your device.
+ + By doing that you can preview how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy. -Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar. + Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar. + You will firstly need to activate the right environment. Type the following command: -You will firstly need to activate the right environment. Type the following command: +``` +conda activate jupyter-book-env +``` -`conda activate jupyter-book-env` - -(or the environment in which you have installed the TeachBooks package) - -Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command: + (or the environment in which you have installed the `teachbooks` package!) + + Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command: ``` teachbooks build ``` -Alternatively: + Alternatively: ``` jupyter-book build --all ``` -Note: use `--all` for the jupyter-book whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book. + Note: use `--all` for the jupyter-book whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book. -Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following: + Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following: -```{figure} ../figures/buildbook.PNG +```{figure} figures/buildbook.PNG Output ``` -Paste the last line into your browser to see the updated changes. + Paste the last line into your browser to see the updated changes. ```{Note} @@ -480,30 +486,27 @@ Sometimes there are problems building the book. It could be that the building re ``` -If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server] + If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server] 3. If you are satisfied with your changes, you can select the files ready to be added to Git-timeline (staging) -The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*. + The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*. -
- Example Image -
+```{figure} figures/Stage_GitHubDekstop.PNG +width: 50% -4. Add changes to Git-timeline locally (committing). In the field that says `Summary(Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, click the blue button `Commit to repository`. +Staging +``` -5. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repository. After committing, the following screen will pop up. Click on `Push Origin`. +4. Add changes to Git-timeline locally (committing). In the field that says `Summary (Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, click the blue button `Commit to repository`. -
- Example Image -
+5. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repository. After committing, click on `Push Origin` in the top bar. -Alternatively, you can also click on `Push origin` in the top bar. - -
- Example Image -
+```{figure} figures/Push_GitHubDekstop.PNG +width: 100% +Push origin +``` ```` ````` `````` @@ -571,7 +574,7 @@ Note: use `--all` for the jupyter-book whenever building a book to make sure the Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following: -```{figure} ../figures/buildbook.PNG +```{figure} figures/buildbook.PNG Output ``` @@ -659,7 +662,7 @@ Note: use `--all` for the jupyter-book whenever building a book to make sure the Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following: -```{figure} ../figures/buildbook.PNG +```{figure} figures/buildbook.PNG Output ``` @@ -694,9 +697,17 @@ Alternatively, you can also click on `Push origin` in the top bar.
Example Image
+```` +````{tab-item} ... using 'VS Code in your browser' + +Using this feature, you can open VS Code in your browser and edit the files in your repository. This can be really useful for **quick fixes** when you dont want to launch GitHub Dekstop or VS Code. However, we would recommend to limit the use of this feature to quick changes as the other workflows allow for more complex tasks. + +```{include} github_dev.md +``` + ```` ````` `````` ``````` ```````` -````````` \ No newline at end of file +````````` diff --git a/book/workflows/figures/Online_VS0.PNG b/book/workflows/figures/Online_VS0.PNG new file mode 100644 index 0000000..6c3fc61 Binary files /dev/null and b/book/workflows/figures/Online_VS0.PNG differ diff --git a/book/workflows/figures/Push_GitHubDesktop.PNG b/book/workflows/figures/Push_GitHubDesktop.PNG index 49d499d..70c3275 100644 Binary files a/book/workflows/figures/Push_GitHubDesktop.PNG and b/book/workflows/figures/Push_GitHubDesktop.PNG differ diff --git a/book/workflows/figures/Push_GitHubDesktop2.PNG b/book/workflows/figures/Push_GitHubDesktop2.PNG deleted file mode 100644 index ff74fb9..0000000 Binary files a/book/workflows/figures/Push_GitHubDesktop2.PNG and /dev/null differ diff --git a/book/workflows/github_dev.md b/book/workflows/github_dev.md new file mode 100644 index 0000000..9c5b815 --- /dev/null +++ b/book/workflows/github_dev.md @@ -0,0 +1,44 @@ +1. Navigate to the repository you want to work in and make sure you're in the correct branch. +2. Navigate to your main page (`code`) of your repository in GitHub. +3. Press the dot key on your keyboard `.` This will open VS Code. +4. In case you want to add a new file, navigate to the explorer file (the page icon) and click on the `New File` icon. This will create a new file in the folder that you are in. Give it the right extension! + +```{figure} figures/Online_VS0.PNG +name: New File +width: 50% +align: center + +New File +``` + +5. In case you want to make changes to an existing file, navigate to a file and make some changes. + +```{figure} figures/Online_VS1.PNG +name: VS Code in Browser +width: 70% +align: center + +VS Code in Browser +``` +In the bottom left you can see the branch you are working in. + +6. Once all the changes are made it's time to commit and push. GitHub Dev requires you to use git in VS Code. You can do that in the Source Control tab in the activity bar on the left side of the window (it looks like a branching icon). Write your commit message and click on commit & push. +7. Now let's see the result. Go back to your GitHub repo. In the top bar, go to actions. + +```{figure} figures/Online_VS2.PNG +name: GitHub Actions +width: 70% +align: center + +GitHub Actions +``` +You will see the latest commit you just did (in this case text). After the pipeline has run, the yellow icon will turn green. Click on the commit and scroll until you see the title Deployed Branches. + +```{figure} figures/Online_VS3.PNG +name: Deployed Branches +width: 60% +align: center + +Deployed Branches +``` +Click on the link and admire your changes:) \ No newline at end of file diff --git a/book/workflows/user45_check_changes.md b/book/workflows/user45_check_changes.md new file mode 100644 index 0000000..c4d3f0f --- /dev/null +++ b/book/workflows/user45_check_changes.md @@ -0,0 +1,44 @@ + Once all the changes are made, it can be useful to check the changes locally on your device. + + By doing that you can preview how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy. + + Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar. + You will firstly need to activate the right environment. Type the following command: + +``` +conda activate jupyter-book-env +``` + + (or the environment in which you have installed the `teachbooks` package!) + + Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command: + +``` +teachbooks build +``` + + Alternatively: + +``` +jupyter-book build --all +``` + + Note: use `--all` for the jupyter-book whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book. + + Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following: + +```{figure} ../figures/buildbook.PNG + +Output +``` + Paste the last line into your browser to see the updated changes. + +```{Note} + +Sometimes there are problems building the book. It could be that the building requires extensions that are not present in your environment. To prevent issues, make sure to update your environment by routinely updating your packages. You can do this by executing the following line in your environment in the command line. + +`pip install -r requirements.txt --upgrade` + +``` + + If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server] \ No newline at end of file