diff --git a/.gitea/workflows/deploy-pages.yml b/.gitea/workflows/deploy-pages.yml deleted file mode 100644 index 3588b20..0000000 --- a/.gitea/workflows/deploy-pages.yml +++ /dev/null @@ -1,39 +0,0 @@ ---- -name: Build and Deploy Documentation - -on: - push: - branches: - - master - workflow_dispatch: - -jobs: - build-and-deploy: - runs-on: ubuntu-latest - container: - image: gitea.psi.ch/hpce/gitea-pages - env: - JEKYLL_ENV: production - steps: - - name: Checkout repository - uses: actions/checkout@v3 - - - name: Build Jekyll website - run: | - bundle exec jekyll --version - bundle exec jekyll build -d public - - - name: Configure Git - run: | - git config --global user.name "Gitea Actions" - git config --global user.email "actions@gitea.local" - - - name: Push to gitea-pages branch - run: | - git checkout --orphan gitea-pages - git reset --hard - ls -la - cp -r ./public/* . - git add . - git commit -m "Deploy site" - git push -f https://${{secrets.GITHUB_TOKEN}}@gitea.psi.ch/${{ github.repository }}.git gitea-pages diff --git a/.gitignore b/.gitignore index e05415b..2e6d3cc 100644 --- a/.gitignore +++ b/.gitignore @@ -1,10 +1,3 @@ -_site/ -.sass-cache/ -.jekyll-metadata -_pdf -.DS_Store -.idea -vendor/ -.bundle/ -.ruby-gemset -.ruby-version +# mkdocs +.cache/ +site/ diff --git a/404.md b/404.md deleted file mode 100644 index fc5a54b..0000000 --- a/404.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Page Not Found" -search: exclude ---- - -Sorry, but the page you were trying to view does not exist. Try searching for it or looking at the URL to see if it looks correct. diff --git a/Dockerfile b/Dockerfile index 05da615..23e6f76 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,24 +1,4 @@ -FROM alpine:3.13 +FROM docker.io/squidfunk/mkdocs-material:9.7 -WORKDIR /tmp -COPY Gemfile /tmp/ -COPY Gemfile.lock /tmp/ - -RUN apk list -I && apk --no-cache add \ - libatomic readline readline-dev libxml2 libxml2-dev \ - ncurses-terminfo-base ncurses-terminfo \ - libxslt libxslt-dev zlib-dev zlib \ - ruby ruby-dev yaml yaml-dev \ - libffi-dev build-base git nodejs \ - && gem env \ - && gem install etc --no-document \ - && gem install bundler -v 2.4.22 --no-document \ - && pwd \ - && ls -l \ - && bundle install - -VOLUME /src -EXPOSE 4001 - -WORKDIR /src -CMD ["jekyll", "serve", "--livereload", "-H", "0.0.0.0"] +# add some plugins +RUN pip install mkdocs-glightbox=='0.5.*' diff --git a/Gemfile b/Gemfile deleted file mode 100644 index c4e9e6b..0000000 --- a/Gemfile +++ /dev/null @@ -1,23 +0,0 @@ -source "https://rubygems.org" - -# to publish on github page -# gem 'github-pages', group: :jekyll_plugins -gem 'github-pages', "~> 215" - -# to publish without github page -# gem "jekyll-redirect-from", group: :jekyll_plugins -gem "jekyll-redirect-from", "~> 0.16.0" -gem "json", "~> 2.2" -gem "webrick", "~> 1.7.0" -gem "etc", "~> 1.2.0" -gem "bigdecimal", "~> 1.4" -gem 'eventmachine', "~> 1.2.7" -gem 'faraday', "~> 1.4.3" -gem 'addressable', "~> 2.7.0" -gem 'faraday-net_http_persistent', "~> 1.1.0" -gem 'ruby2_keywords', "~> 0.0.4" -gem 'rubyzip', "~> 2.3.0" -# -gem 'ffi', "~> 1.15.3" -gem 'http_parser.rb', "~> 0.6.0" # requires mkdir in /usr/bin/mkdir -gem "jekyll", "~> 3.9.0" diff --git a/Gemfile.lock b/Gemfile.lock deleted file mode 100644 index 5e5a27a..0000000 --- a/Gemfile.lock +++ /dev/null @@ -1,292 +0,0 @@ -GEM - remote: https://rubygems.org/ - specs: - activesupport (6.0.6.1) - concurrent-ruby (~> 1.0, >= 1.0.2) - i18n (>= 0.7, < 2) - minitest (~> 5.1) - tzinfo (~> 1.1) - zeitwerk (~> 2.2, >= 2.2.2) - addressable (2.7.0) - public_suffix (>= 2.0.2, < 5.0) - bigdecimal (1.4.4) - coffee-script (2.4.1) - coffee-script-source - execjs - coffee-script-source (1.11.1) - colorator (1.1.0) - commonmarker (0.17.13) - ruby-enum (~> 0.5) - concurrent-ruby (1.2.3) - dnsruby (1.70.0) - simpleidn (~> 0.2.1) - em-websocket (0.5.3) - eventmachine (>= 0.12.9) - http_parser.rb (~> 0) - etc (1.2.0) - ethon (0.16.0) - ffi (>= 1.15.0) - eventmachine (1.2.7) - execjs (2.9.1) - faraday (1.4.3) - faraday-em_http (~> 1.0) - faraday-em_synchrony (~> 1.0) - faraday-excon (~> 1.1) - faraday-net_http (~> 1.0) - faraday-net_http_persistent (~> 1.1) - multipart-post (>= 1.2, < 3) - ruby2_keywords (>= 0.0.4) - faraday-em_http (1.0.0) - faraday-em_synchrony (1.0.0) - faraday-excon (1.1.0) - faraday-net_http (1.0.1) - faraday-net_http_persistent (1.1.0) - ffi (1.15.5) - forwardable-extended (2.6.0) - gemoji (3.0.1) - github-pages (215) - github-pages-health-check (= 1.17.2) - jekyll (= 3.9.0) - jekyll-avatar (= 0.7.0) - jekyll-coffeescript (= 1.1.1) - jekyll-commonmark-ghpages (= 0.1.6) - jekyll-default-layout (= 0.1.4) - jekyll-feed (= 0.15.1) - jekyll-gist (= 1.5.0) - jekyll-github-metadata (= 2.13.0) - jekyll-mentions (= 1.6.0) - jekyll-optional-front-matter (= 0.3.2) - jekyll-paginate (= 1.1.0) - jekyll-readme-index (= 0.3.0) - jekyll-redirect-from (= 0.16.0) - jekyll-relative-links (= 0.6.1) - jekyll-remote-theme (= 0.4.3) - jekyll-sass-converter (= 1.5.2) - jekyll-seo-tag (= 2.7.1) - jekyll-sitemap (= 1.4.0) - jekyll-swiss (= 1.0.0) - jekyll-theme-architect (= 0.1.1) - jekyll-theme-cayman (= 0.1.1) - jekyll-theme-dinky (= 0.1.1) - jekyll-theme-hacker (= 0.1.2) - jekyll-theme-leap-day (= 0.1.1) - jekyll-theme-merlot (= 0.1.1) - jekyll-theme-midnight (= 0.1.1) - jekyll-theme-minimal (= 0.1.1) - jekyll-theme-modernist (= 0.1.1) - jekyll-theme-primer (= 0.5.4) - jekyll-theme-slate (= 0.1.1) - jekyll-theme-tactile (= 0.1.1) - jekyll-theme-time-machine (= 0.1.1) - jekyll-titles-from-headings (= 0.5.3) - jemoji (= 0.12.0) - kramdown (= 2.3.1) - kramdown-parser-gfm (= 1.1.0) - liquid (= 4.0.3) - mercenary (~> 0.3) - minima (= 2.5.1) - nokogiri (>= 1.10.4, < 2.0) - rouge (= 3.26.0) - terminal-table (~> 1.4) - github-pages-health-check (1.17.2) - addressable (~> 2.3) - dnsruby (~> 1.60) - octokit (~> 4.0) - public_suffix (>= 2.0.2, < 5.0) - typhoeus (~> 1.3) - html-pipeline (2.14.3) - activesupport (>= 2) - nokogiri (>= 1.4) - http_parser.rb (0.6.0) - i18n (0.9.5) - concurrent-ruby (~> 1.0) - jekyll (3.9.0) - addressable (~> 2.4) - colorator (~> 1.0) - em-websocket (~> 0.5) - i18n (~> 0.7) - jekyll-sass-converter (~> 1.0) - jekyll-watch (~> 2.0) - kramdown (>= 1.17, < 3) - liquid (~> 4.0) - mercenary (~> 0.3.3) - pathutil (~> 0.9) - rouge (>= 1.7, < 4) - safe_yaml (~> 1.0) - jekyll-avatar (0.7.0) - jekyll (>= 3.0, < 5.0) - jekyll-coffeescript (1.1.1) - coffee-script (~> 2.2) - coffee-script-source (~> 1.11.1) - jekyll-commonmark (1.3.1) - commonmarker (~> 0.14) - jekyll (>= 3.7, < 5.0) - jekyll-commonmark-ghpages (0.1.6) - commonmarker (~> 0.17.6) - jekyll-commonmark (~> 1.2) - rouge (>= 2.0, < 4.0) - jekyll-default-layout (0.1.4) - jekyll (~> 3.0) - jekyll-feed (0.15.1) - jekyll (>= 3.7, < 5.0) - jekyll-gist (1.5.0) - octokit (~> 4.2) - jekyll-github-metadata (2.13.0) - jekyll (>= 3.4, < 5.0) - octokit (~> 4.0, != 4.4.0) - jekyll-mentions (1.6.0) - html-pipeline (~> 2.3) - jekyll (>= 3.7, < 5.0) - jekyll-optional-front-matter (0.3.2) - jekyll (>= 3.0, < 5.0) - jekyll-paginate (1.1.0) - jekyll-readme-index (0.3.0) - jekyll (>= 3.0, < 5.0) - jekyll-redirect-from (0.16.0) - jekyll (>= 3.3, < 5.0) - jekyll-relative-links (0.6.1) - jekyll (>= 3.3, < 5.0) - jekyll-remote-theme (0.4.3) - addressable (~> 2.0) - jekyll (>= 3.5, < 5.0) - jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) - rubyzip (>= 1.3.0, < 3.0) - jekyll-sass-converter (1.5.2) - sass (~> 3.4) - jekyll-seo-tag (2.7.1) - jekyll (>= 3.8, < 5.0) - jekyll-sitemap (1.4.0) - jekyll (>= 3.7, < 5.0) - jekyll-swiss (1.0.0) - jekyll-theme-architect (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-cayman (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-dinky (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-hacker (0.1.2) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-leap-day (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-merlot (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-midnight (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-minimal (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-modernist (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-primer (0.5.4) - jekyll (> 3.5, < 5.0) - jekyll-github-metadata (~> 2.9) - jekyll-seo-tag (~> 2.0) - jekyll-theme-slate (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-tactile (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-theme-time-machine (0.1.1) - jekyll (~> 3.5) - jekyll-seo-tag (~> 2.0) - jekyll-titles-from-headings (0.5.3) - jekyll (>= 3.3, < 5.0) - jekyll-watch (2.2.1) - listen (~> 3.0) - jemoji (0.12.0) - gemoji (~> 3.0) - html-pipeline (~> 2.2) - jekyll (>= 3.0, < 5.0) - json (2.7.1) - kramdown (2.3.1) - rexml - kramdown-parser-gfm (1.1.0) - kramdown (~> 2.0) - liquid (4.0.3) - listen (3.8.0) - rb-fsevent (~> 0.10, >= 0.10.3) - rb-inotify (~> 0.9, >= 0.9.10) - mercenary (0.3.6) - mini_portile2 (2.8.5) - minima (2.5.1) - jekyll (>= 3.5, < 5.0) - jekyll-feed (~> 0.9) - jekyll-seo-tag (~> 2.1) - minitest (5.21.2) - multipart-post (2.3.0) - nokogiri (1.15.5) - mini_portile2 (~> 2.8.2) - racc (~> 1.4) - octokit (4.25.1) - faraday (>= 1, < 3) - sawyer (~> 0.9) - pathutil (0.16.2) - forwardable-extended (~> 2.6) - public_suffix (4.0.7) - racc (1.7.3) - rb-fsevent (0.11.2) - rb-inotify (0.10.1) - ffi (~> 1.0) - rexml (3.2.6) - rouge (3.26.0) - ruby-enum (0.9.0) - i18n - ruby2_keywords (0.0.5) - rubyzip (2.3.2) - safe_yaml (1.0.5) - sass (3.7.4) - sass-listen (~> 4.0.0) - sass-listen (4.0.0) - rb-fsevent (~> 0.9, >= 0.9.4) - rb-inotify (~> 0.9, >= 0.9.7) - sawyer (0.9.2) - addressable (>= 2.3.5) - faraday (>= 0.17.3, < 3) - simpleidn (0.2.1) - unf (~> 0.1.4) - terminal-table (1.8.0) - unicode-display_width (~> 1.1, >= 1.1.1) - thread_safe (0.3.6) - typhoeus (1.4.1) - ethon (>= 0.9.0) - tzinfo (1.2.11) - thread_safe (~> 0.1) - unf (0.1.4) - unf_ext - unf_ext (0.0.9.1) - unicode-display_width (1.8.0) - webrick (1.7.0) - zeitwerk (2.6.12) - -PLATFORMS - ruby - x86_64-linux - -DEPENDENCIES - addressable (~> 2.7.0) - bigdecimal (~> 1.4) - etc (~> 1.2.0) - eventmachine (~> 1.2.7) - faraday (~> 1.4.3) - faraday-net_http_persistent (~> 1.1.0) - ffi (~> 1.15.3) - github-pages (~> 215) - http_parser.rb (~> 0.6.0) - jekyll (~> 3.9.0) - jekyll-redirect-from (~> 0.16.0) - json (~> 2.2) - ruby2_keywords (~> 0.0.4) - rubyzip (~> 2.3.0) - webrick (~> 1.7.0) - -BUNDLED WITH - 2.3.26 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..f251995 --- /dev/null +++ b/LICENSE @@ -0,0 +1,9 @@ +MIT License + +Copyright (c) 2025 PSI + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md index 310b5aa..212de32 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,50 @@ # 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 . +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 . -## Installation +## Development -### Docker +### Using Docker Compose (Recommended) -The easiest and most reproducable way to test changes is using docker. -From the top directory, run the following: +```bash +# Start the development server +docker compose up -```console -$ docker compose build -$ docker compose up +# Or run in background +docker compose up -d ``` -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). +The documentation will be available at `http://localhost:8000`. -### Running locally +> [!NOTE] +> We use several MkDocs plugins, which need to be installed by hand. We do this by +> using a Dockerfile that pulls in the `squidfunk/mkdocs-material` image and runs +> some `pip install` commands. This means that on the first `compose up` call, a +> new docker image will be built locally on your machine. -Building locally requires ruby 2.5 and bundler. To install: +### Deployment -```console -$ gem install bundler jekyll -$ bundle -``` +The site is automatically deployed to `https://hpce.pages.psi.ch/` via Gitea Pages. -To run a local webserver: +## Contributing -```console -$ bundle exec jekyll serve -``` +Please follow established conventions when adding new documentation: -## Theme +1. Use clear, descriptive filenames +2. Follow the existing directory structure +3. Include appropriate metadata in frontmatter +4. Test locally before committing -The theme is derived from the -[Jekyll Doc Theme 6.0](https://github.com/tomjoht/documentation-theme-jekyll) -by Tom Johnson. +## Repository Structure -### Organization +TBD -- Documentation is organized within the `pages` directory -- Add the following frontmatter to each (Merlin6) page: +## Contact - ```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. +For questions or issues with this documentation, contact the HPCE team. ## 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. diff --git a/_config.yml b/_config.yml deleted file mode 100644 index c3bfeba..0000000 --- a/_config.yml +++ /dev/null @@ -1,128 +0,0 @@ -output: web -# this property is useful for conditional filtering of content that is separate from the PDF. - -topnav_title: HPCE@PSI -# this appears on the top navigation bar next to the home button - -site_title: HPC and Emerging Technologies Documentation -# this appears in the html browser tab for the site title (seen mostly by search engines, not users) - -company_name: Paul Scherrer Institute, CSD/HPC and Emerging Technologies Group -# this appears in the footer - -github_editme_path: -# github_editme_path: tomjoht/documentation-theme-jekyll/blob/gh-pages/ -# if you're using Github, provide the basepath to the branch you've created for reviews, following the sample here. if not, leave this value blank. - -# gitlab_editme_path: tomjoht/documentation-theme-jekyll/blob/gh-pages/ -# if you're using GitLab, provide the basepath to the branch you've created for reviews, following the sample here. if not, leave this value blank. - -google_analytics: -#google_analytics: UA-66296557-1 -# if you have google-analytics ID, put it in. if not, edit this value to blank. - -host: 127.0.0.1 -# the preview server used. Leave as is. - -port: 4001 -# the port where the preview is rendered. You can leave this as is unless you have other Jekyll builds using this same port that might cause conflicts. in that case, use another port such as 4006. - -exclude: - - README.md - - .idea/ - - .gitignore - - vendor - - .vscode -# these are the files and directories that jekyll will exclude from the build - -feedback_subject_line: HPCE Documentation feedback - -feedback_email: merlin-admins@lists.psi.ch -# feedback_email: tomjoht@gmail.com -# used as a contact email for the Feedback link in the top navigation bar - -# feedback_disable: true -# if you uncomment the previous line, the Feedback link gets removed - -# feedback_text: "Need help?" -# if you uncomment the previous line, it changes the Feedback text - -# feedback_link: "http://helpy.io/" -# if you uncomment the previous line, it changes where the feedback link points to - -plugins: - - jekyll-redirect-from - -whitelist: - - jekyll-redirect-from - -highlighter: rouge -# library used for syntax highlighting - -markdown: kramdown -kramdown: - input: GFM - auto_ids: true - hard_wrap: false - syntax_highlighter: rouge - -# filter used to process markdown. note that kramdown differs from github-flavored markdown in some subtle ways - -collections: - tooltips: - output: false -# collections are declared here. this renders the content in _tooltips and processes it, but doesn't output it as actual files in the output unless you change output to true - -defaults: - - - scope: - path: "" - type: "pages" - values: - layout: "page" - comments: true - # if you don't want to use Commento.io and just hide comments, change true to false wherever you see the comments property - search: true - sidebar: home_sidebar - topnav: topnav - - - scope: - path: "" - type: "tooltips" - values: - layout: "page" - comments: true - # if you don't want to use Commento.io and just hide comments, change true to false wherever you see the comments property - search: true - tooltip: true - - - - scope: - path: "" - type: "posts" - values: - layout: "post" - comments: true - # if you don't want to use Commento.io and just hide comments, change true to false wherever you see the comments property - search: true - sidebar: home_sidebar - topnav: topnav - -# these are defaults used for the frontmatter for these file types - -sidebars: -- home_sidebar -- mydoc_sidebar -- product1_sidebar -- product2_sidebar -- other - -description: "Merlin is the HPC cluster at Paul Scherrer Institute in Switzerland." -# the description is used in the feed.xml file - -# needed for sitemap.xml file only -url: "https://hpce.pages.psi.ch" -baseurl: / - - -github: [metadata] diff --git a/_data/alerts.yml b/_data/alerts.yml deleted file mode 100644 index 157e162..0000000 --- a/_data/alerts.yml +++ /dev/null @@ -1,15 +0,0 @@ -tip: '