Generate api docs for EESSI test suite

.github/workflows/test.yml

@@ -30,6 +30,15 @@ jobs:
           # config: '/lint/config/changelog.yml'
     #     args: '.'
 
+
+    # Make sure to also test auto-generation of API docs for test suite
+    - name: checkout test suite
+      uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 # v3.1.0
+      with:
+        repository: eessi/test-suite
+        # Path is needed, otherwise this will overwrite the checkout action that cloned the docs repo
+        path: test-suite
+
     - name: install mkdocs + plugins
       run: |
           pip install -r requirements.txt

.github/workflows/update_available_software.yml

@@ -36,7 +36,7 @@ jobs:
 
           export TIME_GENERATED_TEMPLATE="{{ generated_time }}"
           python scripts/available_software/available_software.py
-          ./scripts/update_generated_time.sh mkdocs.yml
+          ./scripts/update_generated_time.sh --section available_software --file mkdocs.yml
 
           git status
 

.github/workflows/update_testsuite_apidocs.yml

@@ -0,0 +1,52 @@
+name: Update API docs for EESSI testsuite
+on:
+  # We manually trigger this right before/after a release of the EESSI test suite
+  # As this is the moment we want to update our API docs
+  # Automation into a Github CI makes sure we don't have to locally build the docs and create a PR every time
+  workflow_dispatch:
+jobs:
+  update_testsuite_apidocs:
+    if: github.repository_owner == 'EESSI'   # Prevent running on forks
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+
+      - name: set up Python
+        uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0
+        with:
+          python-version: '3.10'
+          architecture: x64
+
+      - name: checkout test suite
+        uses: actions/checkout@v4
+        with:
+          repository: eessi/test-suite
+          # Needs to be checked out into a path, otherwise it will overwrite the checkout of the docs repo
+          path: test-suite
+
+      - name: install mkdocs + plugins
+        run: |
+            pip install -r requirements.txt
+            pip list | grep mkdocs
+            mkdocs --version
+
+      - name: build EESSI testsuite api docs
+        id: build_eessi_testsuite_api_docs
+        run: |
+          mkdocs build
+          ./scripts/update_generated_time.sh --section testsuite_api --file mkdocs.yml
+
+      - name: create pull request
+        uses: peter-evans/create-pull-request@6d6857d36972b65feb161a90e484f2984215f83e # v6.0.5
+        if: steps.update_available_software.outputs.json_data_changed == 'yes'
+        with:
+          add-paths: |
+            docs/testsuite_api
+            mkdocs.yml
+          branch: update-testsuite-api-docs
+          branch-suffix: timestamp
+          commit-message: Update of automatically generated API documentation for EESSI test suite
+          title: Update of API documentation for EESSI test suite
+          body: ''
+          token: ${{ secrets.EESSIBOT_GITHUB_TOKEN }}
+          push-to-fork: EESSIbot/docs

docs/generate_eessi_testsuite_api_docs.py

@@ -0,0 +1,50 @@
+"""
+Generate the code reference pages.
+Based off https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages
+"""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+TEST_SUITE = "test-suite/test-suite"
+
+# build a navigation for the menu and a dictionary of navigations for each section
+nav = mkdocs_gen_files.Nav()
+
+# Loop through all python files in test-suite/eessi
+for path in sorted(Path(f"{TEST_SUITE}/eessi/").rglob("*.py")):
+    # Get the relative filename, without .py suffix
+    module_path = path.relative_to(TEST_SUITE).with_suffix("")
+
+    # define the corresponding (relative) markdown filename
+    doc_path = path.relative_to(TEST_SUITE).with_suffix(".md")
+
+    # Specify the full corresponding markdown filename, including a testsuite_api subdir
+    # so that we don't have these API docs scattered in the root of the EESSI docs repo
+    full_doc_path = Path("testsuite_api/", doc_path)
+
+    # If something is an __init__, use the directory name as the name of the python module instead of the filename
+    parts = list(module_path.parts)
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+    # Skip the __main__, if there is one. This is not part of the API
+    elif parts[-1] == "__main__":
+        continue
+
+    # Add an entry for this module to the navigation
+    nav[parts] = doc_path.as_posix()
+
+    # Create the markdown file
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        # identifier is something like eessi.foo.bar
+        identifier = ".".join(parts)
+        fd.write(f"::: {identifier}")
+
+    # This maps the generated .md file to the source .py, so that you can have an "Edit on GitHub" button
+    # that links to the Python code
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+    # Create the api/summary.md file and write the full navigation tree into it so it can be used as a site sidebar
+with mkdocs_gen_files.open("api/summary.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

mkdocs.yml

@@ -56,6 +56,7 @@ nav:
       - Available tests: test-suite/available-tests.md
       - Writing tests: test-suite/writing-portable-tests.md
       - Release notes: test-suite/release-notes.md
+      - API documentation: testsuite_api/
     - Known issues and workarounds:
       - v2023.06: known_issues/eessi-2023.06.md
   - Adding software to EESSI: 
@@ -103,6 +104,24 @@ plugins:
         gpu.md: site_specific_config/gpu.md
   # Enable our custom plugin for json-ld metadata
   - inject_ld_json
+    # link to any Markdown heading
+  - autorefs
+    # api automatics documentation 
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          paths: [test-suite/test-suite] 
+          options:
+            docstring_style: sphinx
+            docstring_section_style: spacy
+            show_source: false
+  - gen-files:
+      scripts:
+          - docs/generate_eessi_testsuite_api_docs.py
+  - literate-nav:
+      nav_file: summary.md
+  - section-index
 markdown_extensions:
   # enable adding HTML attributes and CSS classes
   - attr_list
@@ -137,7 +156,9 @@ extra:
     - icon: fontawesome/brands/twitter
       link: https://twitter.com/eessi_hpc
   # this gets auto-updated via update_generated_time.sh script run in update_available_software.yml action
-  generated_time: "Sat, 26 Apr 2025 at 01:46:16 UTC"
+  generated_time (available software): "Mon, 28 Apr 2025 at 16:32:36 CEST"
+  # this gets auto-updated via update_generated_time.sh script run in update_testsuite_apidocs.yml action
+  generated_time (testsuite API): "Mon, 28 Apr 2025 at 16:33:41 CEST"
 extra_javascript:
   # mermaid diagram
   - https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs

requirements.txt

@@ -5,3 +5,8 @@ mkdocs-git-revision-date-localized-plugin
 mkdocs-toc-sidebar-plugin
 mkdocs-macros-plugin
 ./mkdocs-ldjson-plugin
+mkdocs-autorefs
+mkdocstrings[python]
+mkdocs-gen-files
+mkdocs-literate-nav
+mkdocs-section-index

scripts/update_generated_time.sh

@@ -1,6 +1,72 @@
 #!/usr/bin/env bash
 
+# Default values
+section=""
+file=""
+
+# Print help message
+print_help() {
+    echo "Usage: $0 --section SECTION --file FILE"
+    echo
+    echo Updates the timestamp for the automatically generated docs for the section SECTION in the file FILE
+    echo
+    echo "Valid sections:"
+    echo "  available_software   -> Updates 'generated_time (available software)' field in FILE"
+    echo "  testsuite_api         -> Updates 'generated_time (EESSI testsuite API docs)' field in FILE"
+    echo
+    exit 0
+}
+
+# Parse named options
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --section)
+            section="$2"
+            shift 2
+            ;;
+        --file)
+            file="$2"
+            shift 2
+            ;;
+        --help)
+            print_help
+            ;;
+        *)
+            echo "Unknown option: $1"
+            print_help
+            exit 1
+            ;;
+    esac
+done
+
+# Validate section
+if [[ -z "$section" ]]; then
+    echo "ERROR: --section argument is required."
+    print_help
+    exit 1
+fi
+
+# Validate file
+if [[ -z "$file" ]]; then
+    echo "ERROR: --file argument is required."
+    print_help
+    exit 1
+fi
+
 # Get the new date
 NEW_DATE="$(date '+%a, %d %b %Y at %H:%M:%S %Z')"
-# Inject it into the target file
-sed -i 's/\(generated_time: "\)[^"]*\(".*\)/\1'"${NEW_DATE}"'\2/' $1
+
+# Replace date for requested section
+case "$section" in
+    available_software)
+        sed -E -i 's/(generated_time \(available software\): ")[^"]*(".*)/\1'"${NEW_DATE}"'\2/' $file
+        ;;
+    testsuite_api)
+        sed -E -i 's/(generated_time \(testsuite API\): ")[^"]*(".*)/\1'"${NEW_DATE}"'\2/' $file
+        ;;
+    *)
+        echo "ERROR: Unknown section '$section'"
+        echo "Valid sections are: available_software, testsuite_api"
+        exit 1
+        ;;
+esac