Merge branch 'master' into services-for-courses

Author: rkronberg

.gitignore

@@ -6,11 +6,3 @@ site/
 .DS_Store
 .idea/
 __pycache__/
-
-# These are generated by catalog-hook and only
-# written to the filesystem when MKDOCS_ENV=test:
-docs/apps/index.md
-docs/apps/by_discipline.md
-docs/apps/by_system.md
-
-

.travis.yml

@@ -37,9 +37,8 @@ script:
   # Use long slurm flags
   - bash tests/check_long_slurm_flags.sh
   # There should be no FIXME entires present
-  - bash tests/check_fixme.sh
+# (moved to MkDocs hook) - bash tests/check_fixme.sh
   # Test that no files are masked by folder/index.md
   - bash tests/check_masked.sh
   # Test that all apps have an entry for license
-  - bash tests/check_licenses.sh
-
+# (moved to MkDocs hook) - bash tests/check_licenses.sh

.vscode/tasks.json

@@ -96,7 +96,7 @@
                 "focus": false,
                 "panel": "dedicated",
             },
-            "command": ". ${userHome}/miniconda3/etc/profile.d/conda.sh && conda run --name docs-env --cwd ${workspaceFolder} bash ${workspaceFolder}/tests/run_tests.sh",
+            "command": ". ${userHome}/miniconda3/etc/profile.d/conda.sh && conda run --name docs-env --cwd ${workspaceFolder} MKDOCS_ENV=test bash ${workspaceFolder}/tests/run_tests.sh",
             "windows": {
                 "command": "Write-Host \"The Test task is not configured for running on Windows.\"",
             },

FAQ.md

@@ -23,8 +23,10 @@ The [contributing guide](CONTRIBUTING.md) outlines the basic steps of starting c
   - [How do I add definitions to the glossary / display definitions as tooltips?](#how-do-i-add-definitions-to-the-glossary--display-definitions-as-tooltips)
   - [How do I use the announcement bar?](#how-do-i-use-the-announcement-bar)
   - [How do I include a new software page on the "Applications" index pages](#how-do-i-add-a-new-applications-page)
-  - [How do I add a license tag to an application page?](#how-do-I-add-a-license-tag-to-an-application-page)
-  - [How do I tag an application as available under a web interface?](#how-do-i-tag-an-application-as-available-under-a-web-interface)
+    - [How do I add a license tag to an application page?](#how-do-I-add-a-license-tag-to-an-application-page)
+    - [How do I tag an application as available under a web interface?](#how-do-i-tag-an-application-as-available-under-a-web-interface)
+    - [How do I add scientific disciplines to an application page?](#how-do-i-add-scientific-disciplines-to-an-application-page)
+    - [What if there is no application page, but the application still needs to be listed on the index pages?](#what-if-there-is-no-application-page-but-the-application-still-needs-to-be-listed-on-the-index-pages)
   - [How do I make footnotes?](#how-do-i-make-footnotes)
   - [How do I improve search results?](#how-do-i-improve-search-results)
   - [How do I redirect incoming links](#how-do-i-redirect-incoming-links)
@@ -229,10 +231,10 @@ mkdocs serve --dirtyreload
 You can also run the tests locally with
 
 ```bash
-bash tests/run_tests.sh
+MKDOCS_ENV=test bash tests/run_tests.sh
 ```
 
-The tests depend on the Conda environment, so remember to activate it before running them, or use `conda run -n docs-env bash tests/run_tests.sh`.
+The tests depend on the Conda environment, so remember to activate it before running them, or use `conda run -n docs-env MKDOCS_ENV=test bash tests/run_tests.sh`.
 
 #### Scripts
 
@@ -356,7 +358,7 @@ Documentation for _Material for MkDocs_ has a [search feature](https://squidfunk
 ## How do I add a new "Applications" page?
 
 To include a new software page on the "Applications" index pages
-(`apps/index.md`, `apps/by_system.md`, `apps/by_license.md`, `apps/by_discipline`),
+(`apps/index.md`, `apps/by_discipline`, `apps/by_availability.md`, `apps/by_license.md`),
 you must add a YAML front matter at the beginning of the file (before the page title)
 with appropriate metadata. The frontmatter should look like this:
 
@@ -405,18 +407,47 @@ catalog:
 ---
 ```
 
+A missing name causes even preview builds to stop immediately with an error:
+
+```text
+ERROR   -  Error reading page 'apps/doom.md':
+ERROR   -  Every application in the Software Catalog must have a name
+```
+
+Other missing values in the front matter will generate a warning:
+
+```text
+WARNING -  catalog-hook: Doc file 'apps/doom.md' is for an application, but the YAML front matter does not ...
+```
+
+> [!WARNING]
+> Warnings are **not** allowed in the test automation, so while the site can be built with warnings for a preview (local or Rahti), all of the fields must be defined for a branch to be merged into the master branch.
+
+To include an app page without warnings for missing fields, the app may be marked as "unchecked".
+by defining a boolean-valued key `unchecked: true` inside `catalog:`.:
+
+```yaml
+---
+catalog:
+  name: A name is still required
+  # ...
+  unchecked: true
+---
+```
+
 > [!IMPORTANT]
-> **Do not** edit the index pages by hand, as they are populated automatically by a script using the front matter data when the website is built.
+> **Do not** attempt to _include apps_ on `apps/index.md`, `apps/by_discipline`, `apps/by_availability.md`, `apps/by_license.md` pages by hand, as the indices are populated automatically by a script using the front matter data when the website is built.
 
 See also:
 
 * [How do I add a license tag to an application page?](#how-do-i-add-a-license-tag-to-an-application-page)
 * [How do I tag an application as available under a web interface?](#how-do-i-tag-an-application-as-available-under-a-web-interface)
+* [The 'catalog-hook' configuration file](hooks/catalog/config.yml)
 
-## How do I add a license tag to an application page?
+### How do I add a license tag to an application page?
 
 The license tag is added inside the YAML front matter. Temporarily, the license type should be placed as a
-list item under `tags:` _and_ as a string in `license_type:`:
+single list item under `tags:` _and_ as a string in `license_type:`:
 
 ```yaml
 ---
@@ -432,9 +463,10 @@ catalog:
 where `<license>` is one of the predefined license categories: `Academic`, `Free`, `Non-commercial` or
 `Other`; case sensitive, without the angle brackets.
 
-The application will then be included on the Applications by license page automatically.
+The application will then be included under the appropriate license category on the
+[Applications by license page](https://docs.csc.fi/apps/by_license) automatically.
 
-## How do I tag an application as available under a web interface?
+### How do I tag an application as available under a web interface?
 
 In the YAML front matter. The following would, for example, tag the application as available on
 Puhti, Mahti _and_ Puhti web interface.
@@ -452,6 +484,49 @@ catalog:
 ---
 ```
 
+### How do I add scientific disciplines to an application page?
+
+Similarly to license and availability above. The disciplines are to be listed under `disciplines:`:
+
+```yaml
+---
+catalog:
+  # ...
+  disciplines:
+    - Biosciences
+    - Chemistry
+  # - ...
+  # ...
+---
+```
+
+The application will then be listed under each of those disciplines on the
+[Applications by discipline page](https://docs.csc.fi/apps/by_discipline) automatically.
+
+See [the 'catalog-hook' configuration file](hooks/catalog/config.yml) for a list of predefined
+disciplines.
+
+### What if there is no application page, but the application still needs to be listed on the index pages?
+
+There is an appendix for including such applications. It resides in [the 'catalog-hook' configuration file](hooks/catalog/config.yml). The list `appendix:` contains entries such as
+
+```yaml
+appendix:
+  - name: "Chipster"
+    description: "Easy-to-use analysis platform for RNA-seq, single cell RNA-seq and other NGS data"
+    disciplines:
+      - "Biosciences"
+    doc: "https://chipster.csc.fi/"
+  - name: "MaxQuant"
+    description: "A proteomics software for processing of Mass-spectromtery data"
+    disciplines:
+      - "Biosciences"
+    doc: "support/tutorials/MaxQuant-tutorial.md"
+# - ...
+```
+
+where `doc:` can point either to an external page or a `.md` source file on Docs. For the other fields, see the instructions for application pages above. The fields `name:`, `description:`, `disciplines:` and `doc:` are all required and no other fields are allowed.
+
 ## How do I add footnotes?
 
 Usage of the footnotes feature is described

csc-overrides/apps-index.html

@@ -0,0 +1,12 @@
+{% extends "main.html" %}
+{% block content %}
+{% block breadcrumbs %}
+{{ super() }}
+{% endblock breadcrumbs %}
+{% include "partials/tags.html" %}
+{{ page.content }}
+{% from "partials/apps-list.html" import apps_list with context %}
+{{ apps_list() }}
+{% include "partials/source-file.html" %}
+{% include "partials/feedback.html" %}
+{% endblock content %}

csc-overrides/assets/stylesheets/catalog.css

@@ -1,57 +1,49 @@
-.md-typeset .app-heading-row {
+.md-typeset .catalog-toc {
+  max-width: 80%;
+}
+
+.md-typeset .catalog-toc ul {
   display: flex;
   justify-content: start;
-  align-content: center;
-  margin: 0 0 1.25em;
+  flex-wrap: wrap;
+  margin-left: 0;
+  gap: .25em;
 }
 
-.md-typeset .app-heading {
-  margin: unset;
+.md-typeset .catalog-toc ul li {
+  list-style-type: none;
+  margin: 0;
 }
 
-.md-typeset .app-description {
-  font-weight: 300;
-  text-align: center;
-  color: var(--c-tertiary-800);
-  margin-left: .5ch;
+.md-typeset .catalog-toc ul li a:hover {
+  background-color: unset;
 }
 
-.md-typeset .app-heading-row .app-description {
-  font-size: 1.50em;
+.md-typeset .catalog-toc ul li a[href^="#mahti"] .md-tag {
+  color: var(--c-accent-800);
+  border-color: var(--c-accent-800);
 }
 
-.md-typeset .app-link {
-  margin-right: 1em;
+.md-typeset .catalog-toc ul li a[href^="#mahti"] .md-tag:is(:active, :hover) {
+  background-color: var(--c-accent-100);
 }
 
-.md-typeset nav .app-tags {
-  margin: 0 0 .75em;
+.md-typeset .catalog-toc ul li a[href^="#puhti"] .md-tag {
+  color: var(--c-info-800);
+  border-color: var(--c-info-800);
 }
 
-.md-typeset c-accordion-item {
-  margin-bottom: 1em;
+.md-typeset .catalog-toc ul li a[href^="#puhti"] .md-tag:is(:active, :hover) {
+  background-color: var(--c-info-100);
 }
 
-.md-typeset .alpha-toc {
-  max-width: 80%;
+.md-typeset .catalog-toc ul li a[href^="#lumi"] .md-tag {
+  color: var(--c-black);
+  border-color: var(--c-black);
 }
 
-.md-typeset .alpha-toc ul {
-  display: flex;
-  justify-content: start;
-  flex-wrap: wrap;
-  margin-left: 0;
+.md-typeset .catalog-toc ul li a[href^="#lumi"] .md-tag:is(:active, :hover) {
+  /* background-color: hsl(from black h s calc(l + 96)); */
+  background-color: var(--c-black);
+  color: var(--c-white);
 }
-
-.md-typeset .alpha-toc ul li {
-  list-style-type: none;
-  margin: 0 .25em;
-  text-align: center;
-}
-
-.md-typeset .alpha-toc a {
-  padding: .125em .5em;
-  border-radius: 25%;
-  font-size: large;
-  font-weight: var(--csc-font-weight--bold);
-}

csc-overrides/assets/stylesheets/tags.css

@@ -1,17 +1,24 @@
 .md-typeset .md-tag {
-  border: 1px solid var(--md-primary-fg-color);
-  color: var(--md-primary-fg-color);
-  background-color: transparent;
+  border: 1px solid var(--c-link-700);
+  color: var(--c-link-700);
+  background-color: var(--c-white);
   border-radius: 15px;
   font-weight: 400;
   text-decoration: none;
+  transition:
+    color 125ms,
+    background-color 125ms;
+}
+
+.md-typeset .md-tag:is(:active, :hover) {
+  background-color: var(--c-link-100);
 }
 
 .md-typeset :target>.md-tag {
-  color: var(--md-primary-bg-color);
-  background-color: var(--md-primary-fg-color);
+  color: var(--c-white);
+  background-color: var(--c-link-700);
 }
 
-.md-typeset .md-tag:is(:active, :hover) {
-  background-color: var(--md-accent-bg-color);
+.md-typeset :target>.md-tag:is(:active, :hover) {
+  background-color: var(--c-link-500);
 }

csc-overrides/partials/announcement.html

@@ -4,7 +4,7 @@
   a comment (#) to a statement (%)) a line below. Only a
   single line can be uncommented at a time.
 #}
-{# import ".icons/material/coffee.svg" as icon #}
+{% import ".icons/material/coffee.svg" as icon %}
 {# import ".icons/material/chat.svg" as icon #}
 {# import ".icons/material/information.svg" as icon #}
 {# import ".icons/material/alert.svg" as icon #}
@@ -15,11 +15,11 @@
 {# import ".icons/material/dna.svg" as icon #}
 {# import ".icons/material/atom.svg" as icon #}
 {# import ".icons/material/telescope.svg" as icon #}
-{% import ".icons/material/fire.svg" as icon %}
+{# import ".icons/material/fire.svg" as icon #}
 <div class="announcement-icon">{{ icon }}</div>
 {# Put the announcement, in HTML, right under this comment! #}
 <p>
-Call for Roihu pilot projects is now open! <a href="https://research.csc.fi/2025/10/07/roihu-pilot/" target="_blank">Read the article to learn more & apply for early access</a>.
+Welcome to our weekly research support coffee hour on Zoom! <a href="https://csc.fi/en/training-calendar/csc-research-support-coffee-every-wednesday-at-1400-finnish-time-2-2/" target="_blank">Click here for more information.</a>
 </p>
 {# ...and right above _this_ comment. #}
 <div class="announcement-icon announcement-icon-end">{{ icon }}</div>

csc-overrides/partials/apps-list-item.html

@@ -0,0 +1,29 @@
+{%- macro link(app) -%}
+{% set external = app.page is none %}
+{% set internal = not external and not app.is_appendix_app %}
+{% set href = app.url %}
+{%- set props -%}
+href="{{ href }}"{% if external %} target="_blank"{% endif %}
+{%- endset -%}
+{% if external %}
+{% set icon = ".icons/material/open-in-new.svg" %}
+{% elif not internal %}
+{% set icon = ".icons/material/arrow-right-bold-box-outline.svg" %}
+{% endif %}
+{%- set text -%}
+{{ app.name | string }}{%- if external or not internal -%}&nbsp;<span class="twemoji">{%- include icon -%}</span>{%- endif -%}
+{%- endset -%}
+<a {{ props }}>{{ text }}</a>
+{%- endmacro -%}
+
+{%- macro description(app) -%}
+{%- if app.description -%}
+&nbsp;&mdash;&nbsp;{{ app.description }}
+{%- elif app.unchecked -%}
+*
+{%- endif -%}
+{%- endmacro -%}
+
+{%- macro app_item(app) -%}
+<li>{{ link(app) }}{{ description(app) }}</li>
+{%- endmacro -%}