mirror of
https://github.com/TeachBooks/manual.git
synced 2026-11-12 22:35:51 +00:00
Edit and restructering
This commit is contained in:
Tom van Woudenberg
parent
40a1977b7e
commit
43a7b06ec2
9 changed files with 37 additions and 52 deletions
|
|
@ -4,6 +4,7 @@ root: intro
|
|||
parts:
|
||||
- caption: Getting started!
|
||||
chapters:
|
||||
- file: workflows/github
|
||||
- file: installation-and-setup/overview
|
||||
sections:
|
||||
- file: installation-and-setup/extension
|
||||
|
|
@ -20,10 +21,7 @@ parts:
|
|||
- file: installation-and-setup/working-directory
|
||||
- file: installation-and-setup/environments
|
||||
- file: installation-and-setup/jupyter-book-setup
|
||||
- file: workflows/overview
|
||||
sections:
|
||||
- file: workflows/gitlab
|
||||
- file: workflows/github
|
||||
|
||||
- caption: Features
|
||||
chapters:
|
||||
- file: basic-features/overview
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 55 KiB |
BIN
book/workflows/figures/action.png
Normal file
BIN
book/workflows/figures/action.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
BIN
book/workflows/figures/create_new_repository.png
Normal file
BIN
book/workflows/figures/create_new_repository.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 45 KiB |
BIN
book/workflows/figures/set_up_pages.png
Normal file
BIN
book/workflows/figures/set_up_pages.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 87 KiB |
BIN
book/workflows/figures/use_github_pages_website.png
Normal file
BIN
book/workflows/figures/use_github_pages_website.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 76 KiB |
BIN
book/workflows/figures/use_template.png
Normal file
BIN
book/workflows/figures/use_template.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 83 KiB |
|
|
@ -1,58 +1,52 @@
|
|||
# Example using our GitHub template
|
||||
# Your first TeachBook using template
|
||||
|
||||
This page shows you how as an example how to create your own Jupyter Book. It including making an edit to a predefined book and hosting that book online. It doesn't elaborate on the collaborative functionalities of Git.
|
||||
This page shows you how as an example how to start your own Jupyter Book and hosting that book online. It doesn't elaborate on the collaborative functionalities of Git or how to edit the book.
|
||||
|
||||
## Setting up and first baby-editing-steps
|
||||
`````{tab-set}
|
||||
````{tab-item} GitHub template
|
||||
|
||||
### Step 1: Fork book
|
||||
To get started making your Jupyter Book with our functionalities, fork our template book https://github.com/TeachBooks/template :
|
||||
1. To get started making your Jupyter Book with our functionalities, use the [template book](https://github.com/TeachBooks/template) as template:
|
||||
|
||||
|
||||
```{figure} figures/use_template.png
|
||||
:name: use-template
|
||||
```
|
||||
|
||||
Fill in a repository name, this name will be used in the future url of your book:
|
||||
2. Fill in a repository name, this name will be used in the future url of your book:
|
||||
|
||||
|
||||
```{figure} figures/create_new_repository.png
|
||||
:name: create_new_repository
|
||||
```
|
||||
|
||||
### Step 2: Setup GitHub pages with provided Actions
|
||||
Set up the build of your website using GitHub pages by selecting under `Settings` - `Pages` - `Build and deployment` - `Source` - `GitHub Actions`:
|
||||
3. Set source for GitHub pages to under <svg aria-label="Edit repository metadata" role="img" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-gear float-right"> <path d="M8 0a8.2 8.2 0 0 1 .701.031C9.444.095 9.99.645 10.16 1.29l.288 1.107c.018.066.079.158.212.224.231.114.454.243.668.386.123.082.233.09.299.071l1.103-.303c.644-.176 1.392.021 1.82.63.27.385.506.792.704 1.218.315.675.111 1.422-.364 1.891l-.814.806c-.049.048-.098.147-.088.294.016.257.016.515 0 .772-.01.147.038.246.088.294l.814.806c.475.469.679 1.216.364 1.891a7.977 7.977 0 0 1-.704 1.217c-.428.61-1.176.807-1.82.63l-1.102-.302c-.067-.019-.177-.011-.3.071a5.909 5.909 0 0 1-.668.386c-.133.066-.194.158-.211.224l-.29 1.106c-.168.646-.715 1.196-1.458 1.26a8.006 8.006 0 0 1-1.402 0c-.743-.064-1.289-.614-1.458-1.26l-.289-1.106c-.018-.066-.079-.158-.212-.224a5.738 5.738 0 0 1-.668-.386c-.123-.082-.233-.09-.299-.071l-1.103.303c-.644.176-1.392-.021-1.82-.63a8.12 8.12 0 0 1-.704-1.218c-.315-.675-.111-1.422.363-1.891l.815-.806c.05-.048.098-.147.088-.294a6.214 6.214 0 0 1 0-.772c.01-.147-.038-.246-.088-.294l-.815-.806C.635 6.045.431 5.298.746 4.623a7.92 7.92 0 0 1 .704-1.217c.428-.61 1.176-.807 1.82-.63l1.102.302c.067.019.177.011.3-.071.214-.143.437-.272.668-.386.133-.066.194-.158.211-.224l.29-1.106C6.009.645 6.556.095 7.299.03 7.53.01 7.764 0 8 0Zm-.571 1.525c-.036.003-.108.036-.137.146l-.289 1.105c-.147.561-.549.967-.998 1.189-.173.086-.34.183-.5.29-.417.278-.97.423-1.529.27l-1.103-.303c-.109-.03-.175.016-.195.045-.22.312-.412.644-.573.99-.014.031-.021.11.059.19l.815.806c.411.406.562.957.53 1.456a4.709 4.709 0 0 0 0 .582c.032.499-.119 1.05-.53 1.456l-.815.806c-.081.08-.073.159-.059.19.162.346.353.677.573.989.02.03.085.076.195.046l1.102-.303c.56-.153 1.113-.008 1.53.27.161.107.328.204.501.29.447.222.85.629.997 1.189l.289 1.105c.029.109.101.143.137.146a6.6 6.6 0 0 0 1.142 0c.036-.003.108-.036.137-.146l.289-1.105c.147-.561.549-.967.998-1.189.173-.086.34-.183.5-.29.417-.278.97-.423 1.529-.27l1.103.303c.109.029.175-.016.195-.045.22-.313.411-.644.573-.99.014-.031.021-.11-.059-.19l-.815-.806c-.411-.406-.562-.957-.53-1.456a4.709 4.709 0 0 0 0-.582c-.032-.499.119-1.05.53-1.456l.815-.806c.081-.08.073-.159.059-.19a6.464 6.464 0 0 0-.573-.989c-.02-.03-.085-.076-.195-.046l-1.102.303c-.56.153-1.113.008-1.53-.27a4.44 4.44 0 0 0-.501-.29c-.447-.222-.85-.629-.997-1.189l-.289-1.105c-.029-.11-.101-.143-.137-.146a6.6 6.6 0 0 0-1.142 0ZM11 8a3 3 0 1 1-6 0 3 3 0 0 1 6 0ZM9.5 8a1.5 1.5 0 1 0-3.001.001A1.5 1.5 0 0 0 9.5 8Z"></path> </svg>`Settings` - <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-browser">
|
||||
<path d="M0 2.75C0 1.784.784 1 1.75 1h12.5c.966 0 1.75.784 1.75 1.75v10.5A1.75 1.75 0 0 1 14.25 15H1.75A1.75 1.75 0 0 1 0 13.25ZM14.5 6h-13v7.25c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25Zm-6-3.5v2h6V2.75a.25.25 0 0 0-.25-.25ZM5 2.5v2h2v-2Zm-3.25 0a.25.25 0 0 0-.25.25V4.5h2v-2Z"></path>
|
||||
</svg> `Pages` - `Build and deployment` - `Source` - `GitHub Actions`:
|
||||
|
||||
|
||||
```{figure} figures/set_up_pages.png
|
||||
:name: activate_pages
|
||||
```
|
||||
|
||||
Enable the predefined workflow to publish your book under `Actions` - `I understand my workflows, go ahead an enable them`:
|
||||
4. Set repository website as your GitHub Pages website under <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-code UnderlineNav-octicon d-none d-sm-inline">
|
||||
<path d="m11.28 3.22 4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L13.94 8l-3.72-3.72a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215Zm-6.56 0a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042L2.06 8l3.72 3.72a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L.47 8.53a.75.75 0 0 1 0-1.06Z"></path>
|
||||
</svg>`Code`- `About` - <svg aria-label="Edit repository metadata" role="img" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-gear float-right"> <path d="M8 0a8.2 8.2 0 0 1 .701.031C9.444.095 9.99.645 10.16 1.29l.288 1.107c.018.066.079.158.212.224.231.114.454.243.668.386.123.082.233.09.299.071l1.103-.303c.644-.176 1.392.021 1.82.63.27.385.506.792.704 1.218.315.675.111 1.422-.364 1.891l-.814.806c-.049.048-.098.147-.088.294.016.257.016.515 0 .772-.01.147.038.246.088.294l.814.806c.475.469.679 1.216.364 1.891a7.977 7.977 0 0 1-.704 1.217c-.428.61-1.176.807-1.82.63l-1.102-.302c-.067-.019-.177-.011-.3.071a5.909 5.909 0 0 1-.668.386c-.133.066-.194.158-.211.224l-.29 1.106c-.168.646-.715 1.196-1.458 1.26a8.006 8.006 0 0 1-1.402 0c-.743-.064-1.289-.614-1.458-1.26l-.289-1.106c-.018-.066-.079-.158-.212-.224a5.738 5.738 0 0 1-.668-.386c-.123-.082-.233-.09-.299-.071l-1.103.303c-.644.176-1.392-.021-1.82-.63a8.12 8.12 0 0 1-.704-1.218c-.315-.675-.111-1.422.363-1.891l.815-.806c.05-.048.098-.147.088-.294a6.214 6.214 0 0 1 0-.772c.01-.147-.038-.246-.088-.294l-.815-.806C.635 6.045.431 5.298.746 4.623a7.92 7.92 0 0 1 .704-1.217c.428-.61 1.176-.807 1.82-.63l1.102.302c.067.019.177.011.3-.071.214-.143.437-.272.668-.386.133-.066.194-.158.211-.224l.29-1.106C6.009.645 6.556.095 7.299.03 7.53.01 7.764 0 8 0Zm-.571 1.525c-.036.003-.108.036-.137.146l-.289 1.105c-.147.561-.549.967-.998 1.189-.173.086-.34.183-.5.29-.417.278-.97.423-1.529.27l-1.103-.303c-.109-.03-.175.016-.195.045-.22.312-.412.644-.573.99-.014.031-.021.11.059.19l.815.806c.411.406.562.957.53 1.456a4.709 4.709 0 0 0 0 .582c.032.499-.119 1.05-.53 1.456l-.815.806c-.081.08-.073.159-.059.19.162.346.353.677.573.989.02.03.085.076.195.046l1.102-.303c.56-.153 1.113-.008 1.53.27.161.107.328.204.501.29.447.222.85.629.997 1.189l.289 1.105c.029.109.101.143.137.146a6.6 6.6 0 0 0 1.142 0c.036-.003.108-.036.137-.146l.289-1.105c.147-.561.549-.967.998-1.189.173-.086.34-.183.5-.29.417-.278.97-.423 1.529-.27l1.103.303c.109.029.175-.016.195-.045.22-.313.411-.644.573-.99.014-.031.021-.11-.059-.19l-.815-.806c-.411-.406-.562-.957-.53-1.456a4.709 4.709 0 0 0 0-.582c-.032-.499.119-1.05.53-1.456l.815-.806c.081-.08.073-.159.059-.19a6.464 6.464 0 0 0-.573-.989c-.02-.03-.085-.076-.195-.046l-1.102.303c-.56.153-1.113.008-1.53-.27a4.44 4.44 0 0 0-.501-.29c-.447-.222-.85-.629-.997-1.189l-.289-1.105c-.029-.11-.101-.143-.137-.146a6.6 6.6 0 0 0-1.142 0ZM11 8a3 3 0 1 1-6 0 3 3 0 0 1 6 0ZM9.5 8a1.5 1.5 0 1 0-3.001.001A1.5 1.5 0 0 0 9.5 8Z"></path> </svg> - `Website` - `Use your GitHub Pages Website`
|
||||
|
||||
|
||||
```{figure} figures/use_github_pages_website.png
|
||||
:name: github_pages_as_website
|
||||
```
|
||||
|
||||
### Step 3: Edit the book!
|
||||
Edit a file under `Code` - `book` - A file of your choice - `Edit in place`, in the example below `book/intro.md` is edited:
|
||||
4. Wait a few minutes for the website to be deployed, if you're curious, have a look at the progress under <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-play UnderlineNav-octicon d-none d-sm-inline"> <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path></svg>`Actions` - `All workflows`:
|
||||
|
||||
|
||||
|
||||
Make your edit and `Commit changes` to `main` branch:
|
||||
|
||||
|
||||
|
||||
|
||||
### Step 4: Have a look at the Action
|
||||
Wait a few minutes for the website to be deployed, if you're curious, have a look at the progress under `Actions` - `All workflows`:
|
||||
|
||||
|
||||
|
||||
### Step 5: Visit published website
|
||||
When the workflow has finished, visit your build book at `https://<username>.github.io/<repository_name>` (case sensitive). For our example it is: [https://dummystudent-Tom.github.io/My_own_book](https://dummystudent-Tom.github.io/My_own_book) :
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
It is possible to have multiple versions of a book published at once, by creating another Git branch (e.g. `draft` or `dev`).
|
||||
For each branch, the respective book is published at `https://<username>.github.io/<bookname>/<branchname>`.
|
||||
Technical note: for convenience, just `.../<bookname>/` redirects to `.../<bookname>/book/`, which is itself an alias (a symlink) for
|
||||
`.../<bookname>/main/`.
|
||||
```{figure} figures/action.png
|
||||
:name: action
|
||||
```
|
||||
5. When the workflow has finished, visit your build book at `https://<username>.github.io/<repository_name>` (case sensitive). For our example it is [https://dummydocent.github.io/test_book_from_template/](https://dummydocent.github.io/test_book_from_template/) for the shown repository.
|
||||
|
||||
To learn more about how we do this, please see the [GitHub Actions documentation](https://docs.github.com/en/actions) and our deployment pipeline configuration file `.github/workflows/deploy-book-ghpages.yml` [here](https://github.com/TeachBooks/template/blob/main/.github/workflows/deploy-book-ghpages.yml).
|
||||
|
||||
## Working with GitHub Desktop on this fork
|
||||
````
|
||||
|
||||
Whenever you continue working on this forked template using GitHub Desktop, make sure you select the `For my own purposes` option at `I'll be using this fork...` in the `Fork behavior` tab in `Repository settings`. This will streamline the process:
|
||||
````{tab-item} GitLab template
|
||||
Will follow
|
||||
````
|
||||
`````
|
||||
|
||||
|
||||
Now that you have your book, you can continue editing your book as described in the other chapters in this book
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
# Workflows
|
||||
|
||||
```{warning} Under Construction!
|
||||
|
||||
This page will provide a workflow how to collaborate in Git and GitLab for different uses types. Every team might have a different workflow but this workflow is shown as an example and is used in the MUDE course in CEG.
|
||||
|
||||
An alternative is to use Github and Github pages to publish your book.
|
||||
Loading…
Add table
Add a link
Reference in a new issue