Generate api docs for EESSI test suite

.github/workflows/deploy.yml

@@ -1,6 +1,9 @@
 # documentation: https://help.github.com/en/articles/workflow-syntax-for-github-actions
 name: deploy documentation (only on push to main branch)
 on:
+  schedule: 
+    # schedule the job to run at 12am every Saturday
+    - cron: '0 0 * * 0'
   push:
     branches: main
 # Declare default permissions as read only.
@@ -13,15 +16,21 @@ jobs:
       contents: write
     steps:
     - name: checkout
-      uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 # v3.1.0
+      uses: actions/checkout@v4
       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@v4
       with:
         python-version: '3.10'
-
+
+    - name: checkout test suite
+      uses: actions/checkout@v4
+      with:
+        repository: eessi/test-suite
+        path: src
+
     - name: install mkdocs + plugins
       run: |
           pip install -r requirements.txt

.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@v4
 
     - name: set up Python
-      uses: actions/setup-python@13ae5bb136fac2878aff31522b9efb785519f984 # v4.3.0
+      uses: actions/setup-python@v5
       with:
         python-version: '3.10'
 
@@ -30,6 +30,13 @@ jobs:
           # config: '/lint/config/changelog.yml'
     #     args: '.'
 
+
+    - name: checkout test suite
+      uses: actions/checkout@v4
+      with:
+        repository: eessi/test-suite
+        path: src
+
     - name: install mkdocs + plugins
       run: |
           pip install -r requirements.txt

docs/gen_ref_pages.py

@@ -0,0 +1,79 @@
+"""
+Generate the code reference pages.
+Based off https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages
+"""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+# need to adjust to the test suite hook
+#root = Path(__file__).parent.parent
+
+TEST_SUITE = "src/test-suite"
+#src = TEST_SUITE / "eessi"
+MKDOCS_SEARCH_PRIORITY = """---
+search:
+  boost: 0.5
+---
+"""
+
+# build a navigation for the menu and a dictionary of navigations for each section
+#menu_nav = mkdocs_gen_files.Nav()
+#navs = {}
+nav = mkdocs_gen_files.Nav()
+
+#for path in sorted(src.rglob("*.py")):
+for path in sorted(Path(f"{TEST_SUITE}/eessi/").rglob("*.py")):
+    module_path = path.relative_to(TEST_SUITE).with_suffix("")
+    doc_path = path.relative_to(TEST_SUITE).with_suffix(".md")
+    full_doc_path = Path("api", doc_path)
+
+    #parts = tuple(module_path.parts)
+    parts = list(module_path.parts)
+
+    #if len(parts) > 1 and tuple(parts[:-1]) not in navs:
+    #    navs[tuple(parts[:-1])] = mkdocs_gen_files.Nav()
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        #doc_path = doc_path.with_name("index.md")
+        #full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    # add item to menu navigation
+    #menu_nav[parts] = doc_path.as_posix()
+    nav[parts] = doc_path.as_posix()
+
+    # walk through the parents to the item and add it to each navigation section
+    #for i in range(1, len(parts)):
+    #    nav_tuple = tuple(parts[:-i])
+    #    doc_path_relative_to_nav = doc_path.relative_to("/".join(parts[:len(parts)-i])).as_posix()
+    #    navs[nav_tuple][parts] = doc_path_relative_to_nav
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        #fd.write(MKDOCS_SEARCH_PRIORITY)
+        identifier = ".".join(parts)
+        #fd.write(f"::: {identifier}\n")
+        fd.write(f"::: {identifier}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+    # Generate the menu navigation file
+with mkdocs_gen_files.open("api/summary.md", "w") as nav_file:
+        #nav_file.write(MKDOCS_SEARCH_PRIORITY)
+        #nav_file.writelines(menu_nav.build_literate_nav())
+    nav_file.writelines(nav.build_literate_nav())
+
+ #Generate the section navigation files, appending to any existing API content
+#for key, nav in navs.items():
+#    fp = '/'.join(key)
+#    filename = f"api/{fp}/index.md"
+#
+#    if not Path(filename).is_file():
+#        with mkdocs_gen_files.open(filename, "w") as nav_file:
+#            nav_file.write(MKDOCS_SEARCH_PRIORITY)
+
+#    with mkdocs_gen_files.open(filename, "a") as nav_file:
+#        nav_file.writelines(nav.build_literate_nav())

mkdocs.yml

@@ -43,7 +43,6 @@ nav:
     - Set up environment: using_eessi/setting_up_environment.md
     - Basic commands: using_eessi/basic_commands.md
     - Demos: using_eessi/eessi_demos.md
-    - EESSI in CI: using_eessi/eessi_in_ci.md
   - Advanced usage:
     - Setting up your Stratum: filesystem_layer/stratum1.md
     - Building software with EESSI: using_eessi/building_on_eessi.md
@@ -57,6 +56,7 @@ nav:
       - Release notes: test-suite/release-notes.md
     - Known issues and workarounds:
       - v2023.06: known_issues/eessi-2023.06.md
+  - API documentation: api/
   - Adding software to EESSI: 
     - Overview: adding_software/overview.md
     - For contributors:
@@ -74,7 +74,6 @@ nav:
     - Talks: talks.md
         # - Community meeting (Sept'22): meetings/2022-09-amsterdam.md
     - Contact info: contact.md
-  - Systems where EESSI is available: systems.md
   - Blog: blog/index.md
 plugins:
   - blog:
@@ -96,6 +95,26 @@ plugins:
         contributing_sw/overview.md: adding_software/overview.md
         software_layer/adding_software.md: adding_software/overview.md
         pilot.md: repositories/pilot.md
+    # link to any Markdown heading
+  - autorefs
+    # api automatics documentation 
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          paths: [src/test-suite] 
+          options:
+            docstring_style: sphinx
+            docstring_section_style: spacy
+            show_source: false
+  - gen-files:
+      scripts:
+          - docs/gen_ref_pages.py
+  - literate-nav:
+      nav_file: summary.md
+  - section-index
+
+
 markdown_extensions:
   # enable adding HTML attributes and CSS classes
   - attr_list
@@ -130,7 +149,7 @@ 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, 05 Oct 2024 at 01:44:07 UTC"
+  generated_time: "Fri, 06 Sep 2024 at 12:37:43 UTC"
 extra_javascript:
   # mermaid diagram
   - https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs

requirements.txt

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