A repository for the Sheffield HPC documentation
Shell Roff Makefile CSS Python HTML Other
Clone or download
willfurnass Merge pull request #778 from twinkarma/master
Updated singularity version number, updated tensorflow image listing
Latest commit 85ec956 Jul 13, 2018
Permalink
Failed to load latest commit information.
hpc warning note about Iceberg /fastdata decommissioning May 2, 2018
iceberg Merge pull request #769 from ptheywood/cuda-gencode-documentation Apr 10, 2018
images JupyterHub: add architecture diagram Nov 8, 2017
parallel Fix typo on parallel computing MPI page Mar 27, 2018
sharc Added CPU tensorflow image Jul 13, 2018
themes/tuos Added more Singularity def files Apr 20, 2017
.drone.yml
.gitignore Start adding docs for JupyterHub on ShARC (WIP) Oct 28, 2017
.gitmodules remove the theme submodule Apr 15, 2015
.travis.yml
Dockerfile
LICENSE CC-BY License Dec 7, 2015
Makefile
README.rst
conf.py Enable intersphinx support (for linking to from other docs) Aug 7, 2017
get_newfloat.sty.sh Ensure newfloat.sty is built using sourcde file downloaded from CTAN,… Jan 5, 2018
glossary.rst switch to using the actual glossary thing Dec 22, 2015
index.rst Clarify that computer science is a department May 3, 2017
requirements.txt Start adding docs for JupyterHub on ShARC (WIP) Oct 28, 2017
troubleshooting.rst Add ShARC login node key fingerprints to troubleshooting page Mar 22, 2018

README.rst

https://travis-ci.org/rcgsheffield/sheffield_hpc.svg?branch=master

Sheffield High Performance Computing Documentation

This is the source code for the documentation of Sharc and Iceberg, The University of Sheffield's High Performance Computing clusters. It is written in the rst format.

For a guide on the rst file format see this document.

Rendered Documentation

Two versions of the documentation are currently automatically built from this repository:

How to Contribute

To contribute to this documentation, first you have to fork it on GitHub and clone it to your machine, see Fork a Repo for the GitHub documentation on this process.

Once you have the git repository locally on your computer, you will need to install sphinx and sphinx_bootstrap_theme to be able to build the documentation. See the instructions below for how to achieve this.

Once you have made your changes and updated your Fork on GitHub you will need to Open a Pull Request. All changes to the repository should be made through Pull Requests, including those made by the people with direct push access.

Building the documentation on a local Windows machine

  1. Install Python 3.6 on your machine by downloading and running the Miniconda for Python 3.6 installer:

    • Install for just you;
    • Install to the default location (e.g. C:\Users\myusername\Miniconda3);
    • Do not add Anaconda to your PATH environment variable;
    • Do not register Anaconda as your default Python 3.6.
  2. Click Start -> Anaconda3 (64-bit) -> Anaconda Prompt to open a terminal window.

  3. Create a new conda environment for building the documentation by running the following from this window:

    conda create -n sheffield_hpc python=3.6
    pip install -r requirements.txt
    
  4. To build the HTML documentation run:

    make html
    

    Or if you don't have the make utility installed on your machine then build with sphinx directly:

    sphinx-build . ./html
    
  5. If you want to build the PDF documentation you will need:

    Then from the command line, the following will build the .pdf file:

    make latexpdf
    

    On first run, MikTeX will prompt you to install various extra LaTeX packages.

Building the documentation on a local Linux machine

  1. Ensure Python 3 (ideally Python 3.6) is installed.

  2. Create a virtual environment to install sphinx into:

    mkdir -m 700 ~/.venvs
    python3 -m venv ~/.venvs/sheffield_hpc_py3
    source ~/.venvs/sheffield_hpc_py3/bin/activate
    
  3. Install the Python packages needed to build the HTML documentation:

    pip3 install -r requirements.txt
    
  4. Build the documentation:

    make html
    

Building the documentation on a local Mac machine

  1. Ensure Python 3 (ideally Python 3.6) is installed. If you do not already have a python distribution installed, we recommend you install Miniconda for Python 3.6.

  2. Install the Python packages needed to build the HTML documentation. If you are using (mini)conda create a new conda environment for building the documentation by running:

    export PATH=${HOME}/miniconda3/bin:$PATH
    conda create -n sheffield_hpc python=3.6
    pip install -r requirements.txt
    

    If you are not using (mini)conda to provide Python 3:

    mkdir -m 700 ~/.venvs
    python3 -m venv ~/.venvs/sheffield_hpc_py3
    source ~/.venvs/sheffield_hpc_py3/bin/activate
    pip3 install --requirement requirements.txt
    
  3. To build the HTML documentation run:

    make html
    

Continuous build and serve

The package sphinx-autobuild provides a watcher that automatically rebuilds the site as files are modified. To use it, install (in addition to the Sphinx packages) with the following:

pip install sphinx-autobuild

To start the autobuild process, run:

make livehtml

The application also serves up the site at port 8000 by default at http://localhost:8000.

Making Changes to the Documentation

The documentation consists of a series of reStructured Text files which have the .rst extension. These files are then automatically converted to HTMl and combined into the web version of the documentation by sphinx. It is important that when editing the files the syntax of the rst files is followed. If there are any errors in your changes the build will fail and the documentaion will not update, you can test your build locally by running make html. The easiest way to learn what files should look like is to read the rst files already in the repository.