HPCE Documentation

This site contains internal documentation of HCPE services at Paul Scherrer Institute, particularly the Merlin 6 and Merlin 7 clusters. Live pages are available at https://hpce.pages.psi.ch.

Installation

Docker

The easiest and most reproducable way to test changes is using docker. From the top directory, run the following:

$ docker compose build
$ docker compose up

This will start a webserver on http://0.0.0.0:4001/. Changes to most pages will be automatically reflected in the website (with the exception of changes to config.yml, which requires restarting the webserver).

Running locally

Building locally requires ruby 2.5 and bundler. To install:

$ gem install bundler jekyll
$ bundle

To run a local webserver:

$ bundle exec jekyll serve

Theme

The theme is derived from the Jekyll Doc Theme 6.0 by Tom Johnson.

Organization

• Documentation is organized within the pages directory

• Add the following frontmatter to each (Merlin6) page:

  ---
  title: Introduction
  sidebar: merlin6_sidebar
  permalink: /merlin6/introduction.html
  keywords: key1, key2
  ---
  

• Sidebars are specified in data files, e.g. _data/sidebars/merlin6_sidebar.yml.

• The top menu is controlled by _data/topnav.yml

• News can be addin in _posts. Filenames must include the date.

• Lots of features still need to be configured (e.g. pdf output, tags, etc)

• The search bar uses finds substring of the title, tags, keywords, and summary frontmatter.

Deployment

We use the Gitea workflow (see .gitea/workflow/deploy-pages.yml for details). The pages are automatically re-generated on each push to master branch. The resulting website is stored under the gitea-pages branch, and is automatically exposed.

License

Theme content is licensed under the MIT license. The Navgoco jQuery component used in the sidebar is licensed under the BSD license. See licenses subdirectory for license terms.