Hans-Nikolai Viessmann
3a970492c7
All checks were successful
Build and Deploy Documentation / build-and-deploy (push) Successful in 12s
75 lines
2.0 KiB
Markdown
75 lines
2.0 KiB
Markdown
# 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.
|