Merge branch 'main' into ci

build_env.yml

@@ -32,6 +32,7 @@ dependencies:
   - xz=5.2.6
   - yaml=0.2.5
   - pip:
+      - mkdocs-gen-files==0.5.0
       - mkdocs-glightbox==0.3.7
       - mkdocs-git-revision-date-localized-plugin==1.2.6
       - mkdocs-redirects==1.2.1

docs/cheaha/open_ondemand/ood_matlab.md

@@ -12,7 +12,7 @@ Matlab is available for use graphically in your browser via OOD. As with other s
 
 ## Using Anaconda Python from within Matlab
 
-Matlab has the ability to interoperate with Python from within Matlab. The official documentation for this featuer may be found at <https://www.mathworks.com/help/matlab/call-python-libraries.html>.
+Matlab has the ability to interoperate with Python from within Matlab. The official documentation for this feature may be found at <https://www.mathworks.com/help/matlab/call-python-libraries.html>.
 
 This section is dedicated to using this feature with Anaconda on Cheaha. To use Python contained in an Anaconda Environment within Matlab, please use the following steps.
 

docs/contributing/contributor_guide.md

@@ -96,7 +96,23 @@ Sometimes the Table of Contents, rendered on the right-hand side of pages, can g
 
 Prefer to use commas `,` as separators, quoting entries with double quotes `"` where necessary. These are required by the default table reader plugin settings. Formatting and style are not automated at this time.
 
-Most simple markdown formatting used within CSV Files will be rendered as expected. We encourage cross-linking from within tables to other parts of the documentation, or linking to external resources, as appropriate. Most VSCode markdown extension features do not function within CSV tables, and these are not linted at this time.
+Most simple markdown formatting used within CSV Files will be rendered as expected, while other complex markdown features might not display as expected.
+
+- **Avoid Complex Formatting**
+    - Since markdown linters often ignore content within CSV tables, it is best to avoid complex formatting and limit heavy styling inside these tables.
+- **Control Line Breaks within Table Cells**
+    - Use `<br>` without surrounding spaces for a new line.
+    - Use `<br>&nbsp;` to create a new, indented line within the cell. Including the extra two spaces enhances consistency with unordered lists elsewhere in markdown.
+- **Limitations of CSV Tables**
+    - CSV tables don’t support ordered lists effectively.
+    - Stick to simple bullet lists with two-space indentation.
+    - If a list requires multiple levels or detailed formatting, consider placing the content outside the table. A link to this content can be added to the table to maintain context.
+- **Cross-Linking**
+    - We encourage cross-linking from within tables to other parts of the documentation, or linking to external resources, as appropriate.
+- **Creating Anchors for Internal Links**
+    - When linking within the document, create anchors by using `<span id='$anchor-name'>text</span>`, where `$anchor-name` is the name you wish to use in the internal link and HTTPS URL. The anchor name should be in lowercase with only numerals and dashes `-` as separators. For example:
+        - "Lab PI's" becomes the anchor `lab-pis` and you can format it in the text as `<span id='lab-pis'>Lab PI's</span>`.
+        - Keep anchor names simple, matching headers as closely as possible for consistency across documentation generated by MkDocs material.
 
 #### `mkdocs.yml`
 

docs/data_management/storage.md

@@ -182,7 +182,7 @@ Network scratch is available on the login node and each compute node. This stora
 <!-- markdownlint-disable MD046 -->
 !!! warning
 
-    Research Computing expects each user to keep their scratch areas clean. **The cluster scratch areas are not to be used for archiving data.** In order to keep scratch clear and usable for everyone, files older than 30 days will be automatically deleted.
+    Research Computing expects each user to keep their scratch areas clean. **The cluster scratch areas are not to be used for archiving data.** In order to keep scratch clear and usable for everyone, files older than 30 days will be eligible for deletion.
 <!-- markdownlint-enable MD046 -->
 
 ### Local Scratch
@@ -342,4 +342,4 @@ Managing PHI data can be challenging. There are experts on Campus who can provid
 Data stored in `/scratch` is subject to two limited retention policies.
 
 - Each user will have a quota of 50 TB of scratch storage.
-- Files will be retained for a maximum of 30 days.
+- Files will be retained for a maximum of 30 days, after which they become eligible for deletion.

docs/grants/facilities.md

@@ -4,8 +4,8 @@ The link below contains a plain-text facilities document designed to support res
 
 Download the facilities document file as:
 
-- [Word (.docx)](res/uab-rc-facilities.docx)
-- [plaintext](res/uab-rc-facilities.txt)
+- [Word (.docx)](./res/uab-rc-facilities.docx)
+- [plaintext](./res/uab-rc-facilities.txt)
 
 If you believe that information within is inaccurate or there are missing details, please feel free to contact [Support](../help/support.md).
 

docs/index.md

@@ -36,6 +36,18 @@ RCS is developed and supported by UAB IT's Research Computing Group. We are deve
 
 RCS is an out growth of the UABgrid pilot, launched in September 2007 which has focused on demonstrating the utility of unlimited analysis, storage, and application for research. RCS is built on the same technology foundations used by major cloud vendors and decades of distributed systems computing research, technology that powered the last ten years of large scale systems serving prominent national and international initiatives like the [Open Science Grid](https://osg-htc.org/), [XSEDE](https://www.xsede.org/), the [LHC Computing Grid](https://wlcg.web.cern.ch/), and [NCIP](https://datascience.cancer.gov/).
 
+## How Can I Follow up on ServiceNow Tickets?
+
+If you are unable to find a reference or correspondence for your already submitted ServcieNow ticket, you can now visit UAB's [ServiceNow portal](https://uabprod.service-now.com/service_portal) to track and follow up your submitted tickets. At the website, click the "Log in" button to sign in with your UAB SSO (Single Sign On) credentials.
+
+![Landing page of ServiceNow Portal with the "Log in" button highlighted](images/servicenow_landing_page.png)
+
+When logged in you will see in the top right corner a "My tickets" button. Click on this and you will see two options: "View all open tickets" and "View all tickets".
+
+![ServiceNow Portal after Logging in, highlighting "My tickets" options](images/servicenow_landing_page_tickets.png)
+
+Select the option appropriate for your need. The "View all open tickets" will show you a list of tickets you currently have open (i.e. unresolved), while the "View all tickets" option would show you a list of tickets you have ever submitted, open or closed.
+
 ## Outreach
 
 The UAB IT Research Computing Group has collaborated with a number of prominent research projects at UAB to identify use cases and develop requirements. Our collaborators include, but are not limited to, the Center for Clinical and Translational Science (CCTS), Heflin Genomics Center, the Comprehensive Cancer Center (CCC), the Department of Computer and Information Sciences (CIS), the Department of Mechanical Engineering (ME), Lister Hill Library, the School of Optometry's Center for the Development of Functional Imaging, and Health System Information Services (HSIS).

mkdocs.yml

@@ -43,6 +43,9 @@ plugins:
   - search
   - table-reader:
       data_path: docs
+  - gen-files:
+      scripts:
+        - scripts/pandoc_generator.py
   - git-revision-date-localized:
       type: date
       strict: false
@@ -86,9 +89,6 @@ exclude_docs: |
 not_in_nav: |
   /**/res/*.md
 
-hooks:
-  - scripts/pre_build.py
-
 nav:
   - Home: index.md
   - Account Management:
@@ -199,3 +199,6 @@ validation:
     anchors: warn
     absolute_links: warn
     unrecognized_links: warn
+
+watch:
+  - scripts

scripts/pandoc_generator.py

@@ -0,0 +1,57 @@
+import logging
+from pathlib import Path, PurePath
+from typing import Literal
+
+import mkdocs_gen_files
+import pypandoc
+
+log = logging.getLogger(f"mkdocs.plugins.{__name__}")
+
+
+class Doc:
+    def __init__(self, _path: PurePath) -> None:
+        self._input_path: PurePath = _path
+        self._output_path: PurePath = _path
+
+    def set_output_path(self, _path: PurePath) -> None:
+        self._output_path: PurePath = _path
+
+    def to_docx(self) -> None:
+        self._convert("docx")
+
+    def to_plaintext(self) -> None:
+        self._convert("plain")
+
+    _FORMAT_SUFFIX_MAP = {
+        "docx": ".docx",
+        "plain": ".txt",
+    }
+
+    def _convert(self, _format: Literal["docx", "plain"]) -> None:
+        suffix = self._FORMAT_SUFFIX_MAP[_format]
+
+        # touch the file so mkdocs_gen_files is aware of what we intend
+        # must do this because pypandoc can only write docx directly to disk
+        mkdocs_url_output_path = self._output_path.with_suffix(suffix)
+        with mkdocs_gen_files.open(mkdocs_url_output_path, "w") as f:
+            f.write("")
+
+        # clobber with the actual content
+        pandoc_disk_output_path = (
+            PurePath(mkdocs_gen_files.directory) / mkdocs_url_output_path
+        )
+        pypandoc.convert_file(
+            str(PurePath("docs") / self._input_path),
+            to=_format,
+            extra_args=["--wrap=preserve"],
+            outputfile=str(pandoc_disk_output_path),
+        )
+
+
+def generate() -> None:
+    doc = Doc(PurePath("grants") / "res" / "uab-rc-facilities.md")
+    doc.to_plaintext()
+    doc.to_docx()
+
+
+generate()