Generate api docs for EESSI test suite

.github/workflows/deploy.yml

@@ -3,6 +3,8 @@ name: deploy documentation (only on push to main branch)
 on:
   push:
     branches: main
+  # Add option to deploy manually, e.g. because there is a new EESSI test suite release and we want updated API docs
+  workflow_dispatch:
 # Declare default permissions as read only.
 permissions: read-all
 jobs:
@@ -13,12 +15,12 @@ jobs:
       contents: write
     steps:
     - name: checkout
-      uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 # v3.1.0
+      uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
       with:
         fetch-depth: 0  # need to fetch all history to ensure correct Git revision dates in docs
 
     - name: set up Python
-      uses: actions/setup-python@13ae5bb136fac2878aff31522b9efb785519f984 # v4.3.0
+      uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
       with:
         python-version: '3.10'
 
@@ -28,5 +30,23 @@ jobs:
           pip list | grep mkdocs
           mkdocs --version
 
+    # Make sure to also deploy auto-generated API docs for test suite
+    # For that, we need the repo to be available under eessi/test-suite
+    - name: checkout test suite
+      uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      with:
+        repository: eessi/test-suite
+        # Path is needed, otherwise this will overwrite the checkout action that cloned the docs repo
+        path: test-suite/test-suite
+    - name: generate docs for latest release
+      run: |
+        cd test-suite/test-suite
+        # Make sure to fetch tags, so we can checkout a particular release
+        git fetch --tags
+        # This assumes we stick to a version-tagging scheme vX.Y.Z
+        LATEST_VERSION=$(git tag | grep '^v[0-9]\+\.[0-9]\+\.[0-9]\+$' | sort -t. -k 1,1n -k 2,2n -k 3,3n | tail -1)
+        # Use the latest release by default
+        git checkout $LATEST_VERSION
+
     - name: build tutorial
       run: make test && make deploy

.github/workflows/test.yml

@@ -8,10 +8,10 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
     - name: checkout
-      uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 # v3.1.0
+      uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
 
     - name: set up Python
-      uses: actions/setup-python@13ae5bb136fac2878aff31522b9efb785519f984 # v4.3.0
+      uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
       with:
         python-version: '3.10'
 
@@ -30,6 +30,25 @@ jobs:
           # config: '/lint/config/changelog.yml'
     #     args: '.'
 
+
+    # Make sure to also test deployment of auto-generated API docs for test suite
+    # For that, we need the repo to be available under eessi/test-suite
+    - name: checkout test suite
+      uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      with:
+        repository: eessi/test-suite
+        # Path is needed, otherwise this will overwrite the checkout action that cloned the docs repo
+        path: test-suite/test-suite
+    - name: Generate docs for latest release
+      run: |
+        cd test-suite/test-suite
+        # Make sure to fetch tags, so we can checkout a particular release
+        git fetch --tags
+        # This assumes we stick to a version-tagging scheme vX.Y.Z
+        LATEST_VERSION=$(git tag | grep '^v[0-9]\+\.[0-9]\+\.[0-9]\+$' | sort -t. -k 1,1n -k 2,2n -k 3,3n | tail -1)
+        # Use the latest release by default
+        git checkout $LATEST_VERSION
+        git branch
     - name: install mkdocs + plugins
       run: |
           pip install -r requirements.txt

.gitignore

@@ -2,4 +2,4 @@ site/
 venv*
 scripts/available_software/__pycache__
 scripts/available_software/tests/__pycache__
-
+test-suite

docs/adding_software/debugging_failed_builds.md

@@ -227,7 +227,7 @@ eb --easystack eessi-2023.06-eb-4.8.1-2021b.yml --robot
 After some time, this build fails while trying to build `Plumed`, and we can access the build log to look for clues on why it failed.
 
 ## Building an individual package
-First, prepare the environment by following the [Starting the EESSI software environment][#starting-the-eessi-software-environment] and [Configure EasyBuild](#configure-easybuild) above.
+First, prepare the environment by following the [Starting the EESSI software environment](#starting-the-eessi-software-environment) and [Configure EasyBuild](#configure-easybuild) above.
 
 In our [example PR](https://github.com/EESSI/software-layer/pull/360), the individual package that was added to `eessi-2023.06-eb-4.8.1-2021b.yml` was `LAMMPS-23Jun2022-foss-2021b-kokkos.eb`. To mimic the build behaviour, we'll also have to (re)use any options that are listed in the easystack file for `LAMMPS-23Jun2022-foss-2021b-kokkos.eb`, in this case the option `--from-pr 19000`. Thus, to build, we run:
 ```

docs/generate_eessi_testsuite_api_docs.py

@@ -0,0 +1,55 @@
+"""
+Generate the code reference pages.
+Based off https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages
+"""
+
+import os
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+TEST_SUITE = "test-suite/test-suite"
+
+if not os.path.isdir(TEST_SUITE):
+    raise FileNotFoundError(f"Error: {TEST_SUITE} does not exist. Please clone the eessi/test-suite in a test-suite dir.")
+
+# 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("testsuite_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/
       # - Dashboard: test-suite/dashboard.md
     - Known issues and workarounds:
       - v2023.06: known_issues/eessi-2023.06.md
@@ -105,6 +106,24 @@ plugins:
         rocm.md: site_specific_config/rocm.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

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