diff --git a/config/templates/hpc.template b/config/templates/hpc.template index 12b4ede07b03..bad25e0a2056 100644 --- a/config/templates/hpc.template +++ b/config/templates/hpc.template @@ -91,6 +91,7 @@ plugins: - exclude-search: exclude: - content/HPC/* + - available_software/custom/* markdown_extensions: diff --git a/mkdocs/docs/HPC/only/gent/available_software/README.txt b/mkdocs/docs/HPC/only/gent/available_software/README.txt new file mode 100644 index 000000000000..66eb2fd5145e --- /dev/null +++ b/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) \ No newline at end of file diff --git a/mkdocs/docs/HPC/only/gent/available_software/custom/AlphaFold.md b/mkdocs/docs/HPC/only/gent/available_software/custom/AlphaFold.md new file mode 100644 index 000000000000..9bfc7122a14f --- /dev/null +++ b/mkdocs/docs/HPC/only/gent/available_software/custom/AlphaFold.md @@ -0,0 +1 @@ +We have a dedicated page on AlphaFold available [here](../../../../alphafold.md). \ No newline at end of file diff --git a/mkdocs/docs/HPC/only/gent/available_software/custom/MATLAB.md b/mkdocs/docs/HPC/only/gent/available_software/custom/MATLAB.md new file mode 100644 index 000000000000..a5435515c297 --- /dev/null +++ b/mkdocs/docs/HPC/only/gent/available_software/custom/MATLAB.md @@ -0,0 +1 @@ +We have a dedicated page on MATLAB available [here](../../../../MATLAB.md). \ No newline at end of file diff --git a/mkdocs/docs/HPC/only/gent/available_software/custom/OpenFOAM.md b/mkdocs/docs/HPC/only/gent/available_software/custom/OpenFOAM.md new file mode 100644 index 000000000000..ef07e68b4415 --- /dev/null +++ b/mkdocs/docs/HPC/only/gent/available_software/custom/OpenFOAM.md @@ -0,0 +1 @@ +We have a dedicated page on OpenFOAM available [here](../../../../openFOAM.md). diff --git a/mkdocs/docs/HPC/only/gent/available_software/custom/Python.md b/mkdocs/docs/HPC/only/gent/available_software/custom/Python.md new file mode 100644 index 000000000000..345a9980b301 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/mkdocs/docs/HPC/only/gent/available_software/custom/README.md b/mkdocs/docs/HPC/only/gent/available_software/custom/README.md new file mode 100644 index 000000000000..0cfb3a83dc24 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/scripts/available_software/README.md b/scripts/available_software/README.md index f48a8d2c2235..ac6eccd1aee1 100644 --- a/scripts/available_software/README.md +++ b/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 diff --git a/scripts/available_software/available_software.py b/scripts/available_software/available_software.py index 4df01adf639b..075adff6fad4 100644 --- a/scripts/available_software/available_software.py +++ b/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,6 +369,7 @@ 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"]) @@ -374,6 +377,9 @@ def generate_software_detail_page( 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: