arctraining/hpc1-docs

A HPC1 Documentation repository

This is a template repository that can be used when generating documentation using Jupyter-books and hosting the site via GitHub pages.

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/hpc1-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.