Available Modules: Custom inserted text

config/templates/hpc.template

@@ -91,6 +91,7 @@ plugins:
   - exclude-search:
       exclude:
         - content/HPC/*
+        - available_software/custom/*
 
 
 markdown_extensions:

mkdocs/docs/HPC/only/gent/available_software/README.txt

@@ -0,0 +1,14 @@
+# Available Software
+
+This folder contains the following automatically generated directories:
+- `detail/`: contains detailed software pages that are generated by the script `available_software.py`.
+- `data/`: contains the data that is used to generate the detailed software pages
+
+and the following manually created directories:
+
+- `custom/`: contains custom markdown files that can be inserted into the detailed software pages.
+- `javascript/`: contains the javascript that is used to generate the overview table.
+
+For more info on the purpose of these directories, see the README at scripts/available_software/README.md
+
+(this is a txt as to not be included in the mkdocs build)

mkdocs/docs/HPC/only/gent/available_software/custom/AlphaFold.md

@@ -0,0 +1 @@
+We have a dedicated page on AlphaFold available [here](../../../../alphafold.md).

mkdocs/docs/HPC/only/gent/available_software/custom/MATLAB.md

@@ -0,0 +1 @@
+We have a dedicated page on MATLAB available [here](../../../../MATLAB.md).

mkdocs/docs/HPC/only/gent/available_software/custom/OpenFOAM.md

@@ -0,0 +1 @@
+We have a dedicated page on OpenFOAM available [here](../../../../openFOAM.md).

mkdocs/docs/HPC/only/gent/available_software/custom/Python.md

@@ -0,0 +1,2 @@
+We have a dedicated page on Python available [here](../../../../python.md).
+For more info on Python virtual environments, check out [this page](../../../../setting_up_python_virtual_environments.md)

mkdocs/docs/HPC/only/gent/available_software/custom/README.md

@@ -0,0 +1,4 @@
+# Custom text for available software
+
+This folder must contain markdown files precisely matching names of software packages available on the HPC cluster.
+The MarkDown in these files will be included in the available_software/detail pages.

scripts/available_software/README.md

@@ -36,6 +36,48 @@ You can run the script with following command:
 python available_software.py
 ```
 
+## Adding custom text to a software page
+
+Some software pages benefit from having additional information. For example, a link to software specific documentation.
+
+Custom markdown file located in `mkdocs/docs/HPC/only/gent/available_software/custom` will be inserted into the detailed software page.
+This file must match the name of the module exactly.
+
+For example:
+
+- `mkdocs/docs/HPC/only/gent/available_software` 
+  - `custom/`
+    - ...
+    - Python.md
+    - ...
+  - `detail/`
+    - ...
+    - Python.md
+    - ...
+
+Where the content of `custom/Python.md` is:
+
+```md
+We have a dedicated page on Python available [here](../../../../python.md).
+For more info on python virtual environments, check out [this page](../../../../setting_up_python_virtual_environments.md)
+```
+
+After running `available_software.py`, the contents of `detail/Python.md` will be 
+
+```md
+Python
+======
+
+We have a dedicated page on Python available [here](../../../../python.md).
+For more info on python virtual environments, check out [this page](../../../../setting_up_python_virtual_environments.md)
+
+# Available modules
+
+
+The overview below shows which Python installations are available per HPC-UGent Tier-2 cluster, ordered based on software version (new to old).
+...
+```
+
 ## Testing
 You can run the tests by running the `test.sh` script.
 ```shell

scripts/available_software/available_software.py

@@ -78,8 +78,9 @@ def main():
     print("Done!")
     print("Generate detailed pages... ", end="", flush=True)
     detail_folder = os.path.join(root_dir, "mkdocs/docs/HPC/only/gent/available_software/detail")
+    custom_text_folder = os.path.join(root_dir, "mkdocs/docs/HPC/only/gent/available_software/custom")
     generated_time_yml = os.path.join(root_dir, "mkdocs/extra/gent.yml")  # yml containing time the data was generated
-    generate_detail_pages(json_path, detail_folder, generated_time_yml)
+    generate_detail_pages(json_path, detail_folder, custom_text_folder, generated_time_yml)
     print("Done!")
 
 
@@ -359,6 +360,7 @@ def generate_software_detail_page(
         software_name: str,
         software_data: dict,
         clusters: list,
+        custom_text_folder: str,
         path: str
 ) -> None:
     """
@@ -367,13 +369,17 @@ def generate_software_detail_page(
     @param software_name: Name of the software
     @param software_data: Additional information about the software (version, etc...)
     @param clusters: List with all the cluster names
+    @param custom_text_folder: Path to the folder with custom text for the software
     @param path: Path of the directory where the detailed page will be created.
     """
     sorted_versions = dict_sort(software_data["versions"])
     newest_version = list(sorted_versions.keys())[-1]
 
     filename = f"{path}/{software_name}.md"
     md_file = MdUtils(file_name=filename, title=f"{software_name}")
+
+    md_file.write(get_custom_markdown_text(software_name, custom_text_folder))
+
     md_file.new_header(level=1, title="Available modules")
 
     md_file.new_paragraph(f"The overview below shows which {software_name} installations are available per HPC-UGent "
@@ -399,7 +405,24 @@ def generate_software_detail_page(
         f.write("---\nhide:\n  - toc\n---\n" + read_data)
 
 
-def generate_detail_pages(json_path, dest_path, generated_time_yml) -> None:
+def get_custom_markdown_text(software_name: str, custom_text_folder: str) -> str:
+    """
+    Get the custom Markdown text that will be added to the detailed Markdown pages.
+
+    @return: Custom Markdown text
+    """
+    custom_markdown_path = os.path.join(custom_text_folder, software_name + ".md")
+
+    if not os.path.exists(custom_markdown_path):
+        return ""
+
+    print(f"Adding custom text for {software_name} located at {custom_markdown_path}")
+
+    with open(custom_markdown_path, 'r') as f:
+        return "\n" + f.read() + "\n"
+
+
+def generate_detail_pages(json_path, dest_path, custom_text_folder, generated_time_yml) -> None:
     """
     Generate all the detailed pages for all the software that is available.
     """
@@ -412,7 +435,7 @@ def generate_detail_pages(json_path, dest_path, generated_time_yml) -> None:
 
     all_clusters = data["clusters"]
     for software, content in data["software"].items():
-        generate_software_detail_page(software, content, all_clusters, dest_path)
+        generate_software_detail_page(software, content, all_clusters, custom_text_folder, dest_path)
 
 
 def update_generated_time_yml(generated_time_yml, generated_time) -> None: