automatically update documentation paths in release notes

.github/workflows/build_documentation.yml

@@ -79,6 +79,12 @@ jobs:
                 --version "${{ steps.version.outputs.version }}" \
                 --date "$(date +'%d.%m.%Y')" 
 
+            # update paths to documentation version etc in release notes 
+            - name: Update Release Notes
+              if: github.event_name == 'release'
+              run: |
+                python etc/generate_release_notes.py --version "${{ steps.version.outputs.version }}"
+            
             - name: Checkout gh-pages
               uses: actions/checkout@v4
               with:

RELEASE.md.template

@@ -1,7 +1,7 @@
-SLS Detector Package Major Release x.x.x released on xx.xx.202x
+SLS Detector Package {{RELEASE_TYPE}} Release {{VERSION}} released on {{DATE}}
 ===============================================================
 
-This document describes the differences between vx.x.x and v10.0.0  
+This document describes the differences between v{{VERSION}} and v{{PREVIOUS_VERSION}} 
 
 
 
@@ -41,11 +41,11 @@ Experimental support for building the detector client (including python bindings
 ==========================================
 
 
-    Eiger       10.0.0
+    Eiger       {{VERSION}}
-    Jungfrau    10.0.0
+    Jungfrau    {{VERSION}}
-    Mythen3     10.0.0
+    Mythen3     {{VERSION}}
-    Gotthard2   10.0.0
+    Gotthard2   {{VERSION}}
-    Moench      10.0.0
+    Moench      {{VERSION}}
   
 
     On-board Detector Server Upgrade
@@ -60,7 +60,7 @@ Experimental support for building the detector client (including python bindings
             Using command 'update'
 
     Instructions available at
-        https://slsdetectorgroup.github.io/devdoc/serverupgrade.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/serverupgrade.html
 
 
 
@@ -100,7 +100,7 @@ Experimental support for building the detector client (including python bindings
 
 
     Instructions available at
-        https://slsdetectorgroup.github.io/devdoc/firmware.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/firmware.html
 
 
 
@@ -129,9 +129,9 @@ Experimental support for building the detector client (including python bindings
 
     Commands: udpatekernel, kernelversion
     Instructions available at
-        https://slsdetectorgroup.github.io/devdoc/commandline.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/commandline.html
-        https://slsdetectorgroup.github.io/devdoc/detector.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/detector.html
-        https://slsdetectorgroup.github.io/devdoc/pydetector.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/pydetector.html
 
 
 
@@ -149,78 +149,78 @@ Experimental support for building the detector client (including python bindings
     -------------
     
     Installation:
-        https://slsdetectorgroup.github.io/devdoc/installation.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/installation.html
 
     Quick Start Guide:
-        https://slsdetectorgroup.github.io/devdoc/quick_start_guide.html
+        https://slsdetectorgroup.github.io//{{VERSION}}/quick_start_guide.html
 
     Firmware Upgrade:
-        https://slsdetectorgroup.github.io/devdoc/firmware.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/firmware.html
 
     Detector Server upgrade:
-        https://slsdetectorgroup.github.io/devdoc/serverupgrade.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/serverupgrade.html
 
     Detector Simulators:
-        https://slsdetectorgroup.github.io/devdoc/virtualserver.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/virtualserver.html
 
     Consuming slsDetectorPackage:
-        https://slsdetectorgroup.github.io/devdoc/consuming.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/consuming.html
         
     Software Architecture
-        https://slsdetectorgroup.github.io/devdoc/softwarearchitecture.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/softwarearchitecture.html
 
     Set up commands in config file
-        https://slsdetectorgroup.github.io/devdoc/configcommands.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/configcommands.html
         
     Image Size and Output Characteristics
-        https://slsdetectorgroup.github.io/devdoc/dataformat.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/dataformat.html
 
     API Examples:
         https://github.com/slsdetectorgroup/api-examples
 
     Command Line Documentation:
-        https://slsdetectorgroup.github.io/devdoc/commandline.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/commandline.html
 
     C++ API Documentation:
-        https://slsdetectorgroup.github.io/devdoc/detector.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/detector.html
        
     C++ API Example:
-        https://slsdetectorgroup.github.io/devdoc/examples.html#
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/examples.html#
         
     Python API Documentation:
-        https://slsdetectorgroup.github.io/devdoc/pygettingstarted.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/pygettingstarted.html
 
     Python API Example:
-        https://slsdetectorgroup.github.io/devdoc/pyexamples.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/pyexamples.html
 
     Receivers (including custom receiver):
-        https://slsdetectorgroup.github.io/devdoc/receivers.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/receivers.html
-        https://slsdetectorgroup.github.io/devdoc/slsreceiver.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/slsreceiver.html
 
     Detector UDP Header:
-        https://slsdetectorgroup.github.io/devdoc/udpheader.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/udpheader.html
-        https://slsdetectorgroup.github.io/devdoc/udpdetspec.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/udpdetspec.html
 
     Output Data:
-        https://slsdetectorgroup.github.io/devdoc/dataformat.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/dataformat.html
-        https://slsdetectorgroup.github.io/devdoc/fileformat.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/fileformat.html
-        https://slsdetectorgroup.github.io/devdoc/slsreceiverheaderformat.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/slsreceiverheaderformat.html
-        https://slsdetectorgroup.github.io/devdoc/masterfileattributes.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/masterfileattributes.html
-        https://slsdetectorgroup.github.io/devdoc/binaryfileformat.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/binaryfileformat.html
-        https://slsdetectorgroup.github.io/devdoc/hdf5fileformat.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/hdf5fileformat.html
 
     slsReceiver Zmq Format:
-        https://slsdetectorgroup.github.io/devdoc/slsreceiver.html#zmq-json-header-format
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/slsreceiver.html#zmq-json-header-format
 
     TroubleShooting:
-        https://slsdetectorgroup.github.io/devdoc/troubleshooting.html
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/troubleshooting.html
-        https://slsdetectorgroup.github.io/devdoc/troubleshooting.html#receiver-pc-tuning-options
+        https://slsdetectorgroup.github.io/slsDetectorPackage/{{VERSION}}/troubleshooting.html#receiver-pc-tuning-options
         
     Further Documentation:
         https://www.psi.ch/en/detectors/documentation
         
     Info on Releases:
-        https://www.psi.ch/en/detectors/software
+        https://slsdetectorgroup.github.io/slsDetectorPackage/index.html
 
 
     Support

etc/generate_release_notes.py

@@ -0,0 +1,61 @@
+from pathlib import Path
+from datetime import datetime
+from tempfile import template
+import yaml
+import argparse
+
+ROOT_DIR = Path(__file__).resolve().parent.parent 
+
+def extract_release_type(version: str) -> str: 
+    """Extract release type from version string."""
+    parts = version.split('.')
+    if len(parts) != 3:
+        return "Unknown"
+    major, minor, patch = map(int, parts)
+    if minor == 0 and patch == 0:
+        return "Major"
+    elif patch == 0:
+        return "Minor"
+    else:
+        return "Bug Fix"
+    
+def get_previous_version(data_path: Path, version : str) -> str:
+    """Get the previous version from the versions YAML file."""
+    with open(data_path, 'r') as f:
+        data = yaml.safe_load(f)
+
+    prev_version = data['versions'][0]["version"]
+    if prev_version == version: #already updated to new version 
+        prev_version = data['versions'][1]["version"]
+
+    return prev_version
+
+def main(): 
+    parser = argparse.ArgumentParser(description='Update release notes from templated md file')
+    parser.add_argument('--version', type=str, help='Version to use in release notes, if not provided will read from VERSION file')
+    args = parser.parse_args()
+
+    if args.version:
+        version = args.version
+    else:
+        version = Path(ROOT_DIR / "VERSION").read_text().strip()
+
+    release_type = extract_release_type(version)
+
+    prev_version = get_previous_version(ROOT_DIR / "docs/main_index/versions.yaml", version)
+
+    # Read template
+    template = Path(ROOT_DIR / "RELEASE.md.template").read_text()
+
+    # Substitute version and date
+    output = template.replace("{{VERSION}}", version)
+    output = output.replace("{{DATE}}", datetime.now().strftime("%Y-%m-%d"))
+    output = output.replace("{{RELEASE_TYPE}}", release_type)
+    output = output.replace("{{PREVIOUS_VERSION}}", prev_version)
+
+    # Write output
+    Path(ROOT_DIR / "RELEASE.md").write_text(output)
+    print(f"Generated RELEASE.md for version {version}")
+
+if __name__ == "__main__": 
+    main()

etc/updateAPIVersion.py

@@ -6,17 +6,18 @@ Script to update API VERSION file based on the version in VERSION file.
 
 import argparse
 import sys
+from pathlib import Path
 import os
 import re
 import time
 from datetime import datetime
 
 
-SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT_DIR = Path(__file__).resolve().parent.parent 
 
-API_FILE = SCRIPT_DIR + "/slsSupportLib/include/sls/versionAPI.h"
+API_FILE = ROOT_DIR / "slsSupportLib/include/sls/versionAPI.h"
 
-VERSION_FILE = SCRIPT_DIR + "/VERSION"
+VERSION_FILE = ROOT_DIR / "VERSION"
 
 parser = argparse.ArgumentParser(description = 'updates API version')
 parser.add_argument('api_module_name', choices=["APILIB", "APIRECEIVER", "APICTB", "APIGOTTHARD2", "APIMOENCH", "APIEIGER", "APIXILINXCTB", "APIJUNGFRAU", "APIMYTHEN3"], help = 'module name to change api version options are: ["APILIB", "APIRECEIVER", "APICTB", "APIGOTTHARD2", "APIMOENCH", "APIEIGER", "APIXILINXCTB", "APIJUNGFRAU", "APIMYTHEN3"]')
@@ -73,7 +74,7 @@ if __name__ == "__main__":
 
     args = parser.parse_args() 
 
-    api_dir = SCRIPT_DIR + "/" + args.api_dir
+    api_dir = ROOT_DIR / args.api_dir
     
 
     update_api_version(args.api_module_name, api_dir)

etc/updateClientAPIVersion.py

@@ -1,15 +1,15 @@
 # SPDX-License-Identifier: LGPL-3.0-or-other
 # Copyright (C) 2025 Contributors to the SLS Detector Package
 """
-Script to update API VERSION for slsReceiverSoftware or slsDetectorSoftware 
+script to update API VERSION for slsReceiverSoftware or slsDetectorSoftware 
 """ 
 
 import argparse
-import os
+from pathlib import Path
 
 from updateAPIVersion import update_api_version
 
-SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT_DIR = Path(__file__).resolve().parent.parent 
 
 parser = argparse.ArgumentParser(description = 'updates API version')
 parser.add_argument('module_name', nargs="?", choices=["slsDetectorSoftware", "slsReceiverSoftware", "all"], default="all", help = 'module name to change api version options are: ["slsDetectorSoftware", "slsReceiverSoftware, "all"]')
@@ -19,13 +19,13 @@ if __name__ == "__main__":
 
     if args.module_name == "all": 
         client_names = ["APILIB", "APIRECEIVER"]
-        client_directories = [SCRIPT_DIR+"/slsDetectorSoftware", SCRIPT_DIR+"/slsReceiverSoftware"]
+        client_directories = [ROOT_DIR / "slsDetectorSoftware", ROOT_DIR / "slsReceiverSoftware"]
     elif args.module_name == "slsDetectorSoftware": 
         client_names = ["APILIB"]
-        client_directories = [SCRIPT_DIR+"/slsDetectorSoftware"]
+        client_directories = [ROOT_DIR / "slsDetectorSoftware"]
     else: 
         client_names = ["APIRECEIVER"]
-        client_directories = [SCRIPT_DIR+"/slsReceiverSoftware"]
+        client_directories = [ROOT_DIR / "slsReceiverSoftware"]
 	
     for client_name, client_directory in zip(client_names, client_directories): 
         update_api_version(client_name, client_directory)

etc/update_version.py

@@ -5,12 +5,12 @@ Script to update VERSION file with semantic versioning if provided as an argumen
 """
 
 import sys
-import os
+from pathlib import Path
 
 from packaging.version import Version, InvalidVersion
 
 
-SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+SCRIPT_DIR = Path(__file__).resolve().parent.parent 
 
 def get_version():
 
@@ -30,7 +30,7 @@ def get_version():
     
 
 def write_version_to_file(version):
-    version_file_path = os.path.join(SCRIPT_DIR, "VERSION")
+    version_file_path = Path(SCRIPT_DIR / "VERSION")
     with open(version_file_path, "w") as version_file:
         version_file.write(version)
     print(f"Version {version} written to VERSION file.")