Educators Build Your Own Content

Educators Build Your Own Content#

This guide helps you in building your own Data Science for Energy System Modelling course based on a tailor-made Jupyter Book. By following these instructions, you are able to:

Duplicate the content of this course and use it as your learning material, i.e. lectures, or similar.
Set up and deploy a static website like this course using Github Pages action
Modify this course based on the Jupyter Book structure.

Video Tutorial

Before starting, please make sure that you are using the correct python environment that have at least all the python package dependencies from environment.yaml or requirements.txt. The instruction are here if you are using conda (reccomended) and here if you are using pip.

To follow this tutorial, basic usage of Git is a prerequisit. Here are some resources and tutorials to help you get started with Git:

1. Create a New Fork#

Create your fork of this repository by clicking on the figure below.

In the Create a new fork pop-up menu, shown in the figure below, deselect the default Copy the main branch only option.

By doing so, you will reduce further branch creation, required by the workflow.

Fork this repository!

Clicking on the image above will lead directly to the **Create a new fork**

Note: The purpose of this is to retain the initial gh-pages branch, which is needed for the next section.

2. GitHub Pages Setting#

In your fork of this repository, there is a single GitHub Setting that needs modifying:

In the GitHub repository https://github.com/<your-username>/data-science-for-esm, go to the GitHub Settings -> Pages heading.
In the GitHub Pages heading, go to the Branch section, and change the selection from None to gh-pages /root.

Once the branch has been selected, at the top of the page a URL will be provided:

Your site is live at https://<your-username>.github.io/data-science-for-esm.

Clicking on this figure will lead directly to the our **GitHub Pages** settings menu

3. Content Modification#

Modify the content in your computer by cloning your forked data-science-for-esm repository:

git clone https://github.com/<your-username>/data-science-for-esm.git
cd ./data-science-for-esm

You can modify the content by adding, editing and removing markdown (.md) and jupyter notebook (.ipynb) files in the data-science-for--esm folder.

Make sure that all attachments within the markdown and jupyter notebook are included as well.
For a successful deployment of the website, please specify the files and order of those file in the Table Of Contents _toc.yml.
To modify details of the website, such as the author, logo, other relevant GitHub and Google Collab links, modify the _config.yml.

you can test run the changes locally by running the jupyter-book build data-science-for-esm command.

This command is in charge generating the HTML code which you can open from your browser.
You can then run jupyter-book clean data-science-for-esm to remove the generated build.
Further readings on how jupyter-book build works are here

3a. Add your own logo#

If you want your institution to be placed in the top left corner of this website, we recommend that you follow these steps:

name your institue logo in as logo_int.png and place it inside the data-science-for-esm folder.
Run oet-extension/merge_logo.py to combine your institute with as smaller image of TU Berlin’s and OET’s logo
Within _config.yml, make sure that the logo is directed to logo: logo_merged.png.

4. Deploy Settings#

In the .github/workflows/deploy.ymlfile of the cloned repository, specify the branch other than the gh-pages, to be used by the workflow:

on:
  # Trigger the workflow on push to the main branch
  push:
    branches:
    - main

Upon the git push command to the specified branch, which in this example is the main branch, the workflow will be triggered.

git status
git add .
git commit -m 'new changes applied'
git push

5. GitHub Workflow Deployment#

After a successful git push, Github will the deploy any workflow within the .github/workflows/ folder.

The workflow deployment is tracked by your repository’s status indicator, in this case a beige-brown dot ⏺

This will take minutes to finished, especially for complex python commands in the Jupyter Notebooks.
Clicking on it will show the running status, and the deployment details.

Deployment status upon `git push` to the branch specified in the `deploy.yml` file

Upon the deployment finalization, the status indicator turns to:

successful: a green thick 🗸
- you should be able to see the changes taking place, after some moments, at the specified https://<your-username>.github.io/data-science-for-esm
unsuccessful: a red cross mark 🗶
- indicating an error in the _toc.yml, or one of the content files, which need to be revisited.

Successful deployment, after a finalized `jupyter-book build` run