admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-12 22:35:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

set3

Browse source
This commit is contained in:
Julie Kirsch 2024-11-05 21:03:29 +01:00
parent c872028868
commit 2f6943ad37
6 changed files with 39 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

4
book/examples/live_code.md
View file

@ -17,9 +17,9 @@ align: center
---
Rocket Button
```
To activate the live coding, the rocket button has to be activated like in the figure above. It's always useful to point this out in the beginning of the chapter because it might not be obvious to new users. Here's a not eused in the MUDE book
To activate the live coding, the rocket button has to be activated like in the figure above. It's always useful to point this out in the beginning of the chapter because it might not be obvious to new users. Here's a note used in the MUDE book.
```{Interactive Pages—Use Python in your Browser!}
```{Note} Interactive Pages — Use Python in your Browser!
This online textbook has a number of pages that are set up to be used interactively. You can use the “Live Code” button under the Rocket Ship icon in the top right to activate the interactive features and use Python interactively!
Sometimes the interactivity will involve completing an exercise, wheras on other pages it might simply provide the opportunity to edit the contents of code cells and execute it to explore the page contents interactively. Other pages may provide interactive figures (e.g., widgets).

1
book/features/live_code.ipynb
View file

@ -153,6 +153,7 @@
"metadata": {},
"source": [
"## Alternative with JupyterLite (less well integrated)\n",
"\n",
"Another option to use python in your browser is to use JupyterLite. However, this doesn't give a similar seamless interface. You could create 'iframe-like' Ipython consoles / jupyterbook / jupyter lab environments in your book. As these 'iframes' are separate modules added to your page, the integration with the other content in your book is less flexible as with our sphinx-thebe extension. Furthermore, the best way to use a JupyterLite session would be a separate repo with the jupyter lab interface anyway, so you get the full browser experience. Alternatively, the ipython REPL better can be usefull, as shown here: https://teachbooks.github.io/learn-python/main/Python_Toolbox.html."
]
}

2
book/features/widgets.ipynb
View file

@ -6,7 +6,7 @@
"source": [
"# Ipywidgets\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).\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](../examples/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",

4
book/helper_code/intro.md
View file

@ -4,7 +4,7 @@ This chapter contains a few scripts which can be useful in the book-editing proc
- [LaTeX to markdown conversion](../external/latex-to-markdown-conversion/README.md) to convert a LaTeX file into jupyter-book compatible markdown.
- [Snippitall](Snippitall) to insert the same code snippet at a certain point in each md file in a specific folder and all subfolder.
- [Snippitonce](Snippitonce) to insert the same code snippet at a certain point in each md file only in a specific folder.
- [Extensionchecker](extensionchecker) to identify the kind of files present in subfolder
- [Filedownloader](filedownloader) to return the downloadlink for markdown for all files with a specified extension
- [Extensionchecker](Extensionchecker) to identify the kind of files present in subfolder
- [Filedownloader](Filedownloader) to return the downloadlink for markdown for all files with a specified extension
- [Figreturner](figreturner) to return the markdown code for a figure in a specific extension
- [Figshrinker](../external/Useful_python_code/figshrinker.ipynb) to compress JPEG images.

10
book/workflows/collaboration.md
View file

@ -14,13 +14,13 @@ The steps involved are as follows:
1. **Assign a task to yourself (milestones, issues)**
2. **Create your own version of the book as...**
```````{tab-set}
``````{tab-item} ... user type 3...
``````{tab-item} ... user type 3 ...
**... by creating your own version of the book (branching) or selecting existing version:**
- branching
``````
``````{tab-item} ... user type 4 and 5
``````{tab-item} ... user type 4 and 5.
`````{tab-set}
````{tab-item} Open repository for first time...
@ -49,14 +49,14 @@ The steps involved are as follows:
3. **Edit the book as ...**
```````{tab-set}
``````{tab-item} ... user type... 3
``````{tab-item} ... user type 3 ...
**... by directly adding changes on a single file to Git-timeline (committing):**
- adding file or making changes to single file
- committing
``````
``````{tab-item} ... user type 4...
``````{tab-item} ... user type 4 ...
`````{tab-set}
````{tab-item} ... on a brand new version (branch)...
@ -90,7 +90,7 @@ The steps involved are as follows:
````
`````
``````
``````{tab-item} ... user type 5...
``````{tab-item} ... user type 5 ...
`````{tab-set}
````{tab-item} ... on a brand new version (branch)...

56
book/workflows/edit_book.md
View file

@ -366,38 +366,38 @@ Demonstration, video available [here](https://youtu.be/2ttjBevkEP8)
2. Once all the changes are made, it can be useful to check the changes locally on your device.<br />
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.
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:
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:
(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 <path-to-book>
```
Alternatively:
Alternatively:
```
jupyter-book build <path-to-book> --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
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}
@ -407,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
@ -445,38 +445,38 @@ After committing, click the 🔄 button to push our changes to the remote reposi
2. Once all the changes are made, it can be useful to check the changes locally on your device.<br />
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.
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:
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:
(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 <path-to-book>
```
Alternatively:
Alternatively:
```
jupyter-book build <path-to-book> --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
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}
@ -486,11 +486,11 @@ 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*.
```{figure} figures/Stage_GitHubDekstop.PNG
width: 50%