1.14. DIY GitHub Website#

Requires a GitHub account.

1.14.1. Jupyter Book#

Design a website using Jupyter notebooks

Jupyter-Book

1.14.2. Tutorial#

Adapted from their webpage.

In a conda environment, install the package, jupyter-book

conda install -c conda-forge jupyter-book

Create a new book

jupyter-book create mynewbook/

Building the book

jupyter-book build mybookname/

To publish the book to a Github repository, I use ghp-import.

pip install ghp-import
ghp-import -n -p -f _build/html

Then

git add .
git commit -a 
git push

I automated this with a build.sh script:

#!/bin/bash

# Import aliases
shopt -s expand_aliases 
source ~/.bash_aliases  

# Build book and push changes
myconda jupyter-book build . --all 
ghp-import -n -p -f _build/html

To publish you book online, you need to host it on a public repository on Github.

  1. First, log in to GitHub, then go to the “create a new repository” page: new

  2. Next, give your online repository a name and a description. Make your repository public and do not initialize it with a README file, then click “Create repository”.

  3. Now, clone the (currently empty) online repository to a location on your local computer. You can do this via the command line with:

git clone https://github.com/<my-org>/<my-repository-name>

  1. Copy all of your book files and folders into this newly cloned repository. For example, if you created your book locally with jupyter-book create mylocalbook and your new repository is called ”myonlinebook,“ you could do this via the command line with:

cp -r mylocalbook/* myonlinebook/

  1. Now you need to sync your local and remote (i.e., online) repositories. You can do this with the following commands:

bash build.sh

  1. Update the settings for your GitHub pages site:

    • Use the gh-pages branch to host your website.

    • Choose root directory / if you’re building the book in it’s own repository. Choose /docs directory if you’re building documentation with jupyter-book. From the main branch of your book’s root directory (which should contain the _build/html folder

1.15. conda environment#

this one works

pip install jupyter-book==0.15.1 sphinx==5.0.2 pydata-sphinx-theme==0.15.1 sphinx-book-theme==1.0.1 sphinxcontrib-bibtex==2.5.0 sphinx-autobuild==2021.3.14 sphinx-copybutton sphinx-design sphinx-external-toc sphinx-tabs sphinx-togglebutton
Show Source