From 8776887a1eb0348a19516b9e2733c615a200d582 Mon Sep 17 00:00:00 2001 From: Hans-Nikolai Viessmann Date: Wed, 7 Jan 2026 15:17:22 +0100 Subject: [PATCH] initial testing with Zensical This commit is a test run, currently I would stick with MM proper until Zensical is more mature. Hopefully in about half a year. Missing features: - blog for news articles (using template at the moment, not ideal) --- .vscode/settings.json | 6 - Dockerfile | 4 - compose.yml | 7 +- .../gmerlin6/cluster-introduction.md | 0 .../hardware-and-software-description.md | 0 .../gmerlin6/slurm-configuration.md | 0 docs/merlin6/index.md | 2 +- .../quick-start-guide/accessing-slurm.md | 2 +- .../merlin6/quick-start-guide/introduction.md | 2 +- .../slurm-general-docs/running-jobs.md | 28 +- docs/news/index.md | 2 - .../{posts => }/launching-merlin6-docs.md | 9 +- docs/news/{posts => }/merlin7-preprod-docs.md | 9 +- overrides/news.html | 24 ++ zensical.toml | 290 ++++++++++++++++++ 15 files changed, 349 insertions(+), 36 deletions(-) delete mode 100644 .vscode/settings.json delete mode 100644 Dockerfile rename docs/{ => merlin6}/gmerlin6/cluster-introduction.md (100%) rename docs/{ => merlin6}/gmerlin6/hardware-and-software-description.md (100%) rename docs/{ => merlin6}/gmerlin6/slurm-configuration.md (100%) delete mode 100644 docs/news/index.md rename docs/news/{posts => }/launching-merlin6-docs.md (60%) rename docs/news/{posts => }/merlin7-preprod-docs.md (82%) create mode 100644 overrides/news.html create mode 100644 zensical.toml diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index 5af001d..0000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,6 +0,0 @@ -// Place your settings in this file to overwrite default and user settings. -{ - "files.associations": { - "*.html": "liquid" - } -} diff --git a/Dockerfile b/Dockerfile deleted file mode 100644 index 23e6f76..0000000 --- a/Dockerfile +++ /dev/null @@ -1,4 +0,0 @@ -FROM docker.io/squidfunk/mkdocs-material:9.7 - -# add some plugins -RUN pip install mkdocs-glightbox=='0.5.*' diff --git a/compose.yml b/compose.yml index b672f06..8d5baa6 100644 --- a/compose.yml +++ b/compose.yml @@ -1,9 +1,8 @@ --- services: - mkdocs: - build: . - # explicitly force live-reloading per https://github.com/squidfunk/mkdocs-material/issues/8478 - command: serve --dev-addr=0.0.0.0:8000 --livereload + zensical: + image: docker.io/zensical/zensical:latest + command: serve --dev-addr=0.0.0.0:8000 security_opt: - no-new-privileges:true volumes: diff --git a/docs/gmerlin6/cluster-introduction.md b/docs/merlin6/gmerlin6/cluster-introduction.md similarity index 100% rename from docs/gmerlin6/cluster-introduction.md rename to docs/merlin6/gmerlin6/cluster-introduction.md diff --git a/docs/gmerlin6/hardware-and-software-description.md b/docs/merlin6/gmerlin6/hardware-and-software-description.md similarity index 100% rename from docs/gmerlin6/hardware-and-software-description.md rename to docs/merlin6/gmerlin6/hardware-and-software-description.md diff --git a/docs/gmerlin6/slurm-configuration.md b/docs/merlin6/gmerlin6/slurm-configuration.md similarity index 100% rename from docs/gmerlin6/slurm-configuration.md rename to docs/merlin6/gmerlin6/slurm-configuration.md diff --git a/docs/merlin6/index.md b/docs/merlin6/index.md index 560a5db..16e0c00 100644 --- a/docs/merlin6/index.md +++ b/docs/merlin6/index.md @@ -3,7 +3,7 @@ ## Slurm clusters * The new Slurm CPU cluster is called **`merlin6`**. -* The new Slurm GPU cluster is called [**`gmerlin6`**](../gmerlin6/cluster-introduction.md) +* The new Slurm GPU cluster is called [**`gmerlin6`**](gmerlin6/cluster-introduction.md) * The old Slurm *merlin* cluster is still active and best effort support is provided. The cluster, was renamed as [**merlin5**](../merlin5/cluster-introduction.md). diff --git a/docs/merlin6/quick-start-guide/accessing-slurm.md b/docs/merlin6/quick-start-guide/accessing-slurm.md index 4a07501..ec347bc 100644 --- a/docs/merlin6/quick-start-guide/accessing-slurm.md +++ b/docs/merlin6/quick-start-guide/accessing-slurm.md @@ -34,7 +34,7 @@ For further information about how to use this cluster, please visit: [**Merlin6 The **Merlin6 GPU cluster** (**`gmerlin6`**) is visible from the login nodes. However, to submit jobs to this cluster, one needs to specify the option `--cluster=gmerlin6` when submitting a job or allocation. -For further information about how to use this cluster, please visit: [**Merlin6 GPU Slurm Cluster documentation**](../../gmerlin6/slurm-configuration.md). +For further information about how to use this cluster, please visit: [**Merlin6 GPU Slurm Cluster documentation**](../gmerlin6/slurm-configuration.md). ### Merlin5 CPU cluster access diff --git a/docs/merlin6/quick-start-guide/introduction.md b/docs/merlin6/quick-start-guide/introduction.md index ac410c9..6d47ce7 100644 --- a/docs/merlin6/quick-start-guide/introduction.md +++ b/docs/merlin6/quick-start-guide/introduction.md @@ -43,7 +43,7 @@ These computational resources are split into **two** different **[Slurm](https:/ * The Merlin6 CPU nodes are in a dedicated **[Slurm](https://slurm.schedmd.com/overview.html)** cluster called [**`merlin6`**](../slurm-configuration.md). * This is the **default Slurm cluster** configured in the login nodes: any job submitted without the option `--cluster` will be submited to this cluster. -* The Merlin6 GPU resources are in a dedicated **[Slurm](https://slurm.schedmd.com/overview.html)** cluster called [**`gmerlin6`**](../../gmerlin6/slurm-configuration.md). +* The Merlin6 GPU resources are in a dedicated **[Slurm](https://slurm.schedmd.com/overview.html)** cluster called [**`gmerlin6`**](../gmerlin6/slurm-configuration.md). * Users submitting to the **`gmerlin6`** GPU cluster need to specify the option ``--cluster=gmerlin6``. ### Merlin5 diff --git a/docs/merlin6/slurm-general-docs/running-jobs.md b/docs/merlin6/slurm-general-docs/running-jobs.md index 162e1f7..c9a5093 100644 --- a/docs/merlin6/slurm-general-docs/running-jobs.md +++ b/docs/merlin6/slurm-general-docs/running-jobs.md @@ -52,7 +52,11 @@ The following settings are the minimum required for running a job in the Merlin #SBATCH --clusters= # Possible values: merlin5, merlin6, gmerlin6 ``` - Refer to the documentation of each cluster ([**`merlin6`**](../slurm-configuration.md),[**`gmerlin6`**](../../gmerlin6/slurm-configuration.md),[**`merlin5`**](../../merlin5/slurm-configuration.md) for further information. + Refer to the documentation of each cluster + [**`merlin6`**](../slurm-configuration.md), + [**`gmerlin6`**](../gmerlin6/slurm-configuration.md), + [**`merlin5`**](../../merlin5/slurm-configuration.md) for further + information. * **Partitions:** except when using the *default* partition for each cluster, one needs to specify the partition: @@ -60,7 +64,11 @@ The following settings are the minimum required for running a job in the Merlin #SBATCH --partition= # Check each cluster documentation for possible values ``` - Refer to the documentation of each cluster ([**`merlin6`**](../slurm-configuration.md),[**`gmerlin6`**](../../gmerlin6/slurm-configuration.md),[**`merlin5`**](../../merlin5/slurm-configuration.md) for further information. + Refer to the documentation of each cluster + [**`merlin6`**](../slurm-configuration.md), + [**`gmerlin6`**](../gmerlin6/slurm-configuration.md), + [**`merlin5`**](../../merlin5/slurm-configuration.md) for further + information. * **[Optional] Disabling shared nodes**: by default, nodes are not exclusive. Hence, multiple users can run in the same node. One can request exclusive node usage with the following option: @@ -74,7 +82,11 @@ The following settings are the minimum required for running a job in the Merlin #SBATCH --time= # Can not exceed the partition `MaxTime` ``` - Refer to the documentation of each cluster ([**`merlin6`**](../slurm-configuration.md),[**`gmerlin6`**](../../gmerlin6/slurm-configuration.md),[**`merlin5`**](../../merlin5/slurm-configuration.md) for further information about partition `MaxTime` values. + Refer to the documentation of each cluster + [**`merlin6`**](../slurm-configuration.md), + [**`gmerlin6`**](../gmerlin6/slurm-configuration.md), + [**`merlin5`**](../../merlin5/slurm-configuration.md) for further information + about partition `MaxTime` values. * **Output and error files**: by default, Slurm script will generate standard output (`slurm-%j.out`, where `%j` is the job_id) and error (`slurm-%j.err`, where `%j` is the job_id) files in the directory from where the job was submitted. Users can change default name with the following options: @@ -92,8 +104,14 @@ The following settings are the minimum required for running a job in the Merlin #SBATCH --hint=nomultithread # Don't use extra threads with in-core multi-threading. ``` - Refer to the documentation of each cluster ([**`merlin6`**](../slurm-configuration.md),[**`gmerlin6`**](../../gmerlin6/slurm-configuration.md),[**`merlin5`**](../../merlin5/slurm-configuration.md) for further information about node configuration and Hyper-Threading. - Consider that, sometimes, depending on your job requirements, you might need also to setup how many `--ntasks-per-core` or `--cpus-per-task` (even other options) in addition to the `--hint` command. Please, contact us in case of doubts. + Refer to the documentation of each cluster + ([**`merlin6`**](../slurm-configuration.md), + [**`gmerlin6`**](../gmerlin6/slurm-configuration.md), + [**`merlin5`**](../../merlin5/slurm-configuration.md) for further information + about node configuration and Hyper-Threading. Consider that, sometimes, + depending on your job requirements, you might need also to setup how many + `--ntasks-per-core` or `--cpus-per-task` (even other options) in addition to + the `--hint` command. Please, contact us in case of doubts. !!! tip In general, for the cluster `merlin6` + + + {% if "navigation.path" in features %} + {% include "partials/path.html" %} + {% endif %} + + +
+ {% if page.meta and page.meta.date %} +
{{ page.meta.date }}
+ {% endif %} + {% block content %} + {% include "partials/content.html" %} + {% endblock %} +
+ +{% endblock %} diff --git a/zensical.toml b/zensical.toml new file mode 100644 index 0000000..e405594 --- /dev/null +++ b/zensical.toml @@ -0,0 +1,290 @@ +[project] +site_name = "HPCE User Documentation" +site_description = "Documentation of the computing resources managed by the HPCE group" +site_author = "HPCE Group" +site_url = "https://hpce.pages.psi.ch" +copyright = """ +Copyright © 2025 HPC and Emerging Technologies Group/CSD @ Paul Scherrer Institut +""" + +# Repository +repo_url = "https://gitea.psi.ch/hpce/gitea-pages" +repo_name = "userdocs" +# TODO unsure if this works, branch needs to be changed from `mkdocs` to `main` +edit_uri = "_edit/mkdocs/docs/" + +# Zensical supports both implicit navigation and explicitly defined navigation. +# If you decide not to define a navigation here then Zensical will simply +# derive the navigation structure from the directory structure of your +# "docs_dir". The definition below demonstrates how a navigation structure +# can be defined using TOML syntax. +# +# Read more: https://zensical.org/docs/setup/navigation/ +# nav = [ +# { "Get started" = "index.md" }, +# { "Markdown in 5min" = "markdown.md" }, +# ] + +# With the "extra_css" option you can add your own CSS styling to customize +# your Zensical project according to your needs. You can add any number of +# CSS files. +# +# The path provided should be relative to the "docs_dir". +# +# Read more: https://zensical.org/docs/customization/#additional-css +# +#extra_css = ["stylesheets/extra.css"] + +# With the `extra_javascript` option you can add your own JavaScript to your +# project to customize the behavior according to your needs. +# +# The path provided should be relative to the "docs_dir". +# +# Read more: https://zensical.org/docs/customization/#additional-javascript +#extra_javascript = ["javascripts/extra.js"] + +# ---------------------------------------------------------------------------- +# Section for configuring theme options +# ---------------------------------------------------------------------------- +[project.theme] +variant = "modern" + +# Zensical allows you to override specific blocks, partials, or whole +# templates as well as to define your own templates. To do this, uncomment +# the custom_dir setting below and set it to a directory in which you +# keep your template overrides. +# +# Read more: +# - https://zensical.org/docs/customization/#extending-the-theme +# +custom_dir = "overrides" + +favicon = "images/favicon.ico" +logo = "images/hpce_logo.png" + +# Zensical supports more than 60 different languages. This means that the +# labels and tooltips that Zensical's templates produce are translated. +# The "language" option allows you to set the language used. This language +# is also indicated in the HTML head element to help with accessibility +# and guide search engines and translation tools. +# +# The default language is "en" (English). It is possible to create +# sites with multiple languages and configure a language selector. See +# the documentation for details. +# +# Read more: +# - https://zensical.org/docs/setup/language/ +# +language = "en" + +# Zensical provides a number of feature toggles that change the behavior +# of the documentation site. +features = [ + # Zensical includes an announcement bar. This feature allows users to + # dismiss it then they have read the announcement. + # https://zensical.org/docs/setup/header/#announcement-bar + "announce.dismiss", + + # If you have a repository configured and turn on this feature, Zensical + # will generate an edit button for the page. This works for common + # repository hosting services. + # https://zensical.org/docs/setup/repository/#code-actions + "content.action.edit", + + # If you have a repository configured and turn on this feature, Zensical + # will generate a button that allows the user to view the Markdown + # code for the current page. + # https://zensical.org/docs/setup/repository/#code-actions + "content.action.view", + + # Code annotations allow you to add an icon with a tooltip to your + # code blocks to provide explanations at crucial points. + # https://zensical.org/docs/authoring/code-blocks/#code-annotations + "content.code.annotate", + + # This feature turns on a button in code blocks that allow users to + # copy the content to their clipboard without first selecting it. + # https://zensical.org/docs/authoring/code-blocks/#code-copy-button + "content.code.copy", + + # Code blocks can include a button to allow for the selection of line + # ranges by the user. + # https://zensical.org/docs/authoring/code-blocks/#code-selection-button + "content.code.select", + + # Zensical can render footnotes as inline tooltips, so the user can read + # the footnote without leaving the context of the document. + # https://zensical.org/docs/authoring/footnotes/#footnote-tooltips + "content.footnote.tooltips", + + # If you have many content tabs that have the same titles (e.g., "Python", + # "JavaScript", "Cobol"), this feature causes all of them to switch to + # at the same time when the user chooses their language in one. + # https://zensical.org/docs/authoring/content-tabs/#linked-content-tabs + "content.tabs.link", + + # TODO: not sure I understand this one? Is there a demo of this in the docs? + # https://zensical.org/docs/authoring/tooltips/#improved-tooltips + "content.tooltips", + + # With this feature enabled, Zensical will automatically hide parts + # of the header when the user scrolls past a certain point. + # https://zensical.org/docs/setup/header/#automatic-hiding + # "header.autohide", + + # Turn on this feature to expand all collapsible sections in the + # navigation sidebar by default. + # https://zensical.org/docs/setup/navigation/#navigation-expansion + # "navigation.expand", + + # This feature turns on navigation elements in the footer that allow the + # user to navigate to a next or previous page. + # https://zensical.org/docs/setup/footer/#navigation + "navigation.footer", + + # When section index pages are enabled, documents can be directly attached + # to sections, which is particularly useful for providing overview pages. + # https://zensical.org/docs/setup/navigation/#section-index-pages + "navigation.indexes", + + # When instant navigation is enabled, clicks on all internal links will be + # intercepted and dispatched via XHR without fully reloading the page. + # https://zensical.org/docs/setup/navigation/#instant-navigation + "navigation.instant", + + # With instant prefetching, your site will start to fetch a page once the + # user hovers over a link. This will reduce the perceived loading time + # for the user. + # https://zensical.org/docs/setup/navigation/#instant-prefetching + "navigation.instant.prefetch", + + # In order to provide a better user experience on slow connections when + # using instant navigation, a progress indicator can be enabled. + # https://zensical.org/docs/setup/navigation/#progress-indicator + #"navigation.instant.progress", + + # When navigation paths are activated, a breadcrumb navigation is rendered + # above the title of each page + # https://zensical.org/docs/setup/navigation/#navigation-path + "navigation.path", + + # When pruning is enabled, only the visible navigation items are included + # in the rendered HTML, reducing the size of the built site by 33% or more. + # https://zensical.org/docs/setup/navigation/#navigation-pruning + #"navigation.prune", + + # When sections are enabled, top-level sections are rendered as groups in + # the sidebar for viewports above 1220px, but remain as-is on mobile. + # https://zensical.org/docs/setup/navigation/#navigation-sections + "navigation.sections", + + # When tabs are enabled, top-level sections are rendered in a menu layer + # below the header for viewports above 1220px, but remain as-is on mobile. + # https://zensical.org/docs/setup/navigation/#navigation-tabs + "navigation.tabs", + + # When sticky tabs are enabled, navigation tabs will lock below the header + # and always remain visible when scrolling down. + # https://zensical.org/docs/setup/navigation/#sticky-navigation-tabs + "navigation.tabs.sticky", + + # A back-to-top button can be shown when the user, after scrolling down, + # starts to scroll up again. + # https://zensical.org/docs/setup/navigation/#back-to-top-button + "navigation.top", + + # When anchor tracking is enabled, the URL in the address bar is + # automatically updated with the active anchor as highlighted in the table + # of contents. + # https://zensical.org/docs/setup/navigation/#anchor-tracking + "navigation.tracking", + + # When search highlighting is enabled and a user clicks on a search result, + # Zensical will highlight all occurrences after following the link. + # https://zensical.org/docs/setup/search/#search-highlighting + "search.highlight", + + # When anchor following for the table of contents is enabled, the sidebar + # is automatically scrolled so that the active anchor is always visible. + # https://zensical.org/docs/setup/navigation/#anchor-following + "toc.follow", + + # When navigation integration for the table of contents is enabled, it is + # always rendered as part of the navigation sidebar on the left. + # https://zensical.org/docs/setup/navigation/#navigation-integration + #"toc.integrate", +] + +# ---------------------------------------------------------------------------- +# In the "palette" subsection you can configure options for the color scheme. +# You can configure different color # schemes, e.g., to turn on dark mode, +# that the user can switch between. Each color scheme can be further +# customized. +# +# Read more: +# - https://zensical.org/docs/setup/colors/ +# ---------------------------------------------------------------------------- +[[project.theme.palette]] +scheme = "default" +toggle.icon = "lucide/sun" +toggle.name = "Switch to dark mode" + +[[project.theme.palette]] +scheme = "slate" +toggle.icon = "lucide/moon" +toggle.name = "Switch to light mode" + +# ---------------------------------------------------------------------------- +# In the "font" subsection you can configure the fonts used. By default, fonts +# are loaded from Google Fonts, giving you a wide range of choices from a set +# of suitably licensed fonts. There are options for a normal text font and for +# a monospaced font used in code blocks. +# ---------------------------------------------------------------------------- +#[project.theme.font] +#text = "Inter" +#code = "Jetbrains Mono" + +# ---------------------------------------------------------------------------- +# You can configure your own logo to be shown in the header using the "logo" +# option in the "icons" subsection. The logo can be a path to a file in your +# "docs_dir" or it can be a path to an icon. +# +# Likewise, you can customize the logo used for the repository section of the +# header. Zensical derives the default logo for this from the repository URL. +# See below... +# +# There are other icons you can customize. See the documentation for details. +# +# Read more: +# - https://zensical.org/docs/setup/logo-and-icons +# - https://zensical.org/docs/authoring/icons-emojis/#search +# ---------------------------------------------------------------------------- +[project.theme.icon] +#logo = "lucide/smile" +#repo = "lucide/smile" + +# ---------------------------------------------------------------------------- +# The "extra" section contains miscellaneous settings. +# ---------------------------------------------------------------------------- +#[[project.extra.social]] +#icon = "fontawesome/brands/github" +#link = "https://github.com/user/repo" + +[project.markdown_extensions.admonition] +[project.markdown_extensions.attr_list] +[project.markdown_extensions.footnotes] +[project.markdown_extensions.tables] +[project.markdown_extensions.pymdownx.blocks.caption] +[project.markdown_extensions.pymdownx.caret] +[project.markdown_extensions.pymdownx.mark] +[project.markdown_extensions.pymdownx.tilde] +[project.markdown_extensions.pymdownx.details] +[project.markdown_extensions.pymdownx.emoji] +emoji_index = "zensical.extensions.emoji.twemoji" +emoji_generator = "zensical.extensions.emoji.to_svg" +[project.markdown_extensions.pymdownx.highlight] +anchor_linenums = true +[project.markdown_extensions.pymdownx.inlinehilite] +[project.markdown_extensions.pymdownx.snippets] +[project.markdown_extensions.pymdownx.superfences] +