diff --git a/book/_toc.yml b/book/_toc.yml index 99201ab..356a7c2 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -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 diff --git a/book/images/image.png b/book/images/image.png deleted file mode 100644 index 63fd66a..0000000 Binary files a/book/images/image.png and /dev/null differ diff --git a/book/workflows/figures/action.png b/book/workflows/figures/action.png new file mode 100644 index 0000000..7cbb008 Binary files /dev/null and b/book/workflows/figures/action.png differ diff --git a/book/workflows/figures/create_new_repository.png b/book/workflows/figures/create_new_repository.png new file mode 100644 index 0000000..58b4e5b Binary files /dev/null and b/book/workflows/figures/create_new_repository.png differ diff --git a/book/workflows/figures/set_up_pages.png b/book/workflows/figures/set_up_pages.png new file mode 100644 index 0000000..ee2d57b Binary files /dev/null and b/book/workflows/figures/set_up_pages.png differ diff --git a/book/workflows/figures/use_github_pages_website.png b/book/workflows/figures/use_github_pages_website.png new file mode 100644 index 0000000..76a03c3 Binary files /dev/null and b/book/workflows/figures/use_github_pages_website.png differ diff --git a/book/workflows/figures/use_template.png b/book/workflows/figures/use_template.png new file mode 100644 index 0000000..c6d21fb Binary files /dev/null and b/book/workflows/figures/use_template.png differ diff --git a/book/workflows/github.md b/book/workflows/github.md index e8fce42..ed73474 100644 --- a/book/workflows/github.md +++ b/book/workflows/github.md @@ -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: -![alt text](../images/image.png) +```{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: -![alt text](../images/image-1.png) +```{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 `Settings` - `Pages` - `Build and deployment` - `Source` - `GitHub Actions`: -![alt text](../images/image-2.png) +```{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 `Code`- `About` - - `Website` - `Use your GitHub Pages Website` -![alt text](../images/image-3.png) +```{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 `Actions` - `All workflows`: -![alt text](../images/image-5.png) - -Make your edit and `Commit changes` to `main` branch: - -![alt text](../images/image-6.png) -![alt text](../images/image-7.png) - -### 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`: - -![alt text](../images/image-8.png) - -### Step 5: Visit published website -When the workflow has finished, visit your build book at `https://.github.io/` (case sensitive). For our example it is: [https://dummystudent-Tom.github.io/My_own_book](https://dummystudent-Tom.github.io/My_own_book) : - -![alt text](../images/image-9.png) - ---- - -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://.github.io//`. -Technical note: for convenience, just `...//` redirects to `...//book/`, which is itself an alias (a symlink) for -`...//main/`. +```{figure} figures/action.png +:name: action +``` +5. When the workflow has finished, visit your build book at `https://.github.io/` (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 +```` +````` -![alt text](./figures/GitHub_desktop_fork.png) \ No newline at end of file +Now that you have your book, you can continue editing your book as described in the other chapters in this book \ No newline at end of file diff --git a/book/workflows/overview.md b/book/workflows/overview.md deleted file mode 100644 index b202ace..0000000 --- a/book/workflows/overview.md +++ /dev/null @@ -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. \ No newline at end of file