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

```console
$ 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:

```console
$ gem install bundler jekyll
$ bundle
```

To run a local webserver:

```console
$ bundle exec jekyll serve
```

## Theme

The theme is derived from the
[Jekyll Doc Theme 6.0](https://github.com/tomjoht/documentation-theme-jekyll)
by Tom Johnson.

### Organization

- Documentation is organized within the `pages` directory
- Add the following frontmatter to each (Merlin6) page:

  ```md
  ---
  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.