Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
hpc
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.rst

https://readthedocs.org/projects/iceberg/badge/?version=latest

Sheffield High Performance Computing Documentation

This is the source for the documentation of Bessemer, ShARC and Iceberg, The University of Sheffield's High Performance Computing clusters.

It is written in the reStructuredText (rst) format and the Sphinx tool is used to convert this to a set of HTML pages.

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

Rendered Documentation

This website is currently automatically built from this repository: each push to the master branch causes the ReadTheDocs service to build and serve the documentation.

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 specific versions of the 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 on your machine by downloading and running the Miniconda 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.
  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 --name sheffield_hpc python=3
    conda activate sheffield_hpc        # . activate sheffield_hpc on older versions of conda
    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
    

Building the documentation on a local Linux machine

  1. Ensure Python 3 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 is installed. If you do not already have a python distribution installed, we recommend you install :ref:`Miniconda <Miniconda installer>`.

  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
    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
    

Check external links

Do this with:

make linkcheck

Continuous build and serve

Build and serve the site and automatically rebuild when source files change:

make livehtml

Testing the building of the documentation

The validity of the reStructuredText in this repo and the ability to convert that to HTML with Sphinx can be tested in three ways:

About

A repository for the Sheffield HPC documentation

Resources

License

Releases

No releases published

Packages

No packages published
You can’t perform that action at this time.