arctraining/hpc0-docs

HPC0 Documentation repository

Welcome to the HPC0 course documentation repository. You can find this site hosted via GitHub pages here.

Working with this project locally

You can get this project working locally by using the environment.yml file to create a conda environment that contains all the dependencies required to get started.

$ git clone https://github.com/ARCTraining/template-jb-docs.git

$ conda env create -f environment.yml

To build the html content locally you can use the jupyter-book command line tool:

# navigate to the repository root
$ cd template-jb-docs
# sometimes worth running jupyter-book clean book/ to remove old files
$ jupyter-book build book/

Windows

An important note is that the JupyterBook project does not currently support Windows (see here for more).

To aid with this we have created a Vagrantfile that can allow Windows users who have a virtualisation provider installed (such as VirtualBox) and Vagrant installed to create a headless virtual Linux machine that will build the jupyter book. You can do this with the following steps once you've installed a virtualisation provider and vagrant:

# within git-bash or powershell
$ cd template-jb-docs
$ vagrant up

# to rebuild the site after changes with the vagrant box running
$ vagrant reload --provision

# don't forget to destroy the box when you're done
$ vagrant destroy

This will build the jupyter-book html files on your Windows file system (by navigating via /vagrant) so your local build will still persist after you've destroyed your vagrant box.