Merge branch 'main' into feat/gh-44-support-math-poc-do-not-merge

.github/CODEOWNERS

@@ -1,17 +1,13 @@
 # https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners#example-of-a-codeowners-file
 
-# global
-# TODO: Ask @susanunit
-# * @susanunit
-
 # architecture
 /*                 @wesleyboar
 /.github/          @wesleyboar
 /user-guide/themes @wesleyboar
 
 # settings
-/user-guide/docs/index.md @wesleyboar @susanunit @cockerilltim
-/user-guide/mkdocs.yml    @wesleyboar @susanunit
+/user-guide/docs/index.md @wesleyboar
+/user-guide/mkdocs.yml    @wesleyboar
 
 # OpenSees
 /user-guide/docs/tools/simulation/opensees.md  @silviamazzoni

.github/workflows/build.yml

@@ -49,7 +49,7 @@ jobs:
         uses: docker/build-push-action@v3
         with:
           push: true
-          tags: designsafeci/ds-user-guide:latest,designsafeci/ds-user-guide:${{ steps.vars.outputs.sha_short }},designsafeci/ds-user-guide:${{ steps.vars.outputs.ref_short }}${{ inputs.tag_custom && ',designsafeci/ds-user-guide:' }}${{ inputs.tag_custom }}
+          tags: designsafeci/ds-user-guide:${{ inputs.tag_custom && inputs.tag_custom || 'latest' }},designsafeci/ds-user-guide:${{ steps.vars.outputs.sha_short }},designsafeci/ds-user-guide:${{ steps.vars.outputs.ref_short }}
       -
         name: Post build status in slack
         id: slack

Dockerfile

@@ -1,4 +1,4 @@
-FROM taccwma/tacc-docs:v0.6.0
+FROM taccwma/tacc-docs:v0.10.1
 
 # To archive TACC content, before replacing it
 RUN mv /docs /docs-from-tacc

Makefile

@@ -1,14 +1,17 @@
+# WARNING: Using `docker-compose` is deprecated
+DOCKER_COMPOSE_CMD := $(shell if command -v docker-compose > /dev/null; then echo "docker-compose"; else echo "docker compose"; fi)
+
 .PHONY: build
 build:
-	docker-compose -f ./docker-compose.yml build
+	$(DOCKER_COMPOSE_CMD) -f ./docker-compose.yml build
 
 .PHONY: start
 start:
-	docker-compose -f docker-compose.yml up
+	$(DOCKER_COMPOSE_CMD) -f docker-compose.yml up
 
 .PHONY: stop
 stop:
-	docker-compose -f docker-compose.yml down
+	$(DOCKER_COMPOSE_CMD) -f docker-compose.yml down
 	# So assets are not re-used (even after `docker system prune --all --force`)
 	docker volume rm ds-user-guide_skip-tacc-js
 	docker volume rm ds-user-guide_skip-tacc-css

README.md

@@ -32,11 +32,11 @@ DesignSafe [MkDocs](https://mkdocs.readthedocs.io/) documentation with **customi
 
 ### A. Via Python
 
-> [!NOTE]
-> This solution uses a different theme than https://designsafe-ci.org/user-guide/.
+> [!IMPORTANT]
+> This method has different theme than [live website](https://designsafe-ci.org/user-guide/) ([#42](https://github.com/DesignSafe-CI/DS-User-Guide/issues/42)) **and** bugs ([#66](https://github.com/DesignSafe-CI/DS-User-Guide/issues/66)).
 
 0. Have Python installed.\
-    <sup>Known supported versions are [from 3.10 to 3.12](https://github.com/DesignSafe-CI/DS-User-Guide/blob/6c22d2f/pyproject.toml).</sup>
+    <sup>Known supported versions are [from 3.10 to 3.12](https://github.com/DesignSafe-CI/DS-User-Guide/blob/tacc/tacc-docs/pyproject.toml#L9).</sup>
 1. Navigate into your clone of this repo.
 2. Install dependencies:\
     <sup>You should only need to do this once, or after a new release.</sup>
@@ -63,21 +63,24 @@ DesignSafe [MkDocs](https://mkdocs.readthedocs.io/) documentation with **customi
 
 ### B. Via Docker
 
+> [!WARNING]
+> This method does **not** work on macOS with an M1 nor M2 chip ([details](https://github.com/DesignSafe-CI/DS-User-Guide/issues/51)).
+
 0. Have Docker installed.\
     <sup>We recommend doing so via [Docker-Desktop](https://www.docker.com/products/docker-desktop).</sup>
 1. Navigate into your clone of this repository.
 2. Start the Docker container to serve the docs. 
 
-   Linux or Mac (macOS) user:
+   Using `Make`:
    ```shell
     make build
     make start
 
     ```
-   Windows user:
+   Or:
    ```shell
-    docker-compose -f docker-compose.yml build
-    docker-compose -f docker-compose.yml up
+    docker compose build
+    docker compose up
 
     ```
 4. Open the website at the URL provided e.g.

user-guide/docs/analysis/hvsrweb.md

@@ -2,31 +2,31 @@
 
 The horizontal-to-vertical spectral ratio (HVSR) method has become an increasingly popular tool for developing a quick and reliable estimate of a site’s fundamental natural frequency (<em>f</em><sub>0</sub>). HVSRweb is an open-source, web-based application for performing HVSR calculations in a convenient, reliable, and statistically-consistent manner. HVSRweb allows the user to upload three-component ambient noise records and perform the HVSR calculation in the cloud, with no installation required. The HVSR calculation can be performed using a single combined horizontal component (e.g., geometric-mean, squared-average) or multiple rotated horizontal components to investigate azimuthal variability. HVSRweb can reject spurious time windows using an automated frequency-domain window-rejection algorithm, removing the need for subjective and time-consuming user interaction. It also facilitates the use of lognormal statistics for <em>f</em><sub>0</sub>, allowing for a consistent statistical framework capable of quantifying measurement uncertainty in terms of either frequency or its reciprocal, period. In addition, HVSRweb presents the opportunity to rapidly incorporate new developments in processing and quantification of uncertainty as they emerge, and encourages standardization of HVSR processing across users while avoiding the challenges associated with traditional approaches that require the user to perform regular updates to keep pace with new developments.
 
-### [Step 1](#step1) { #step1 }
+### Step 1 { #step1 }
 
 ![](./imgs/HVSR-1.png)
 
-### [Step 2](#step2) { #step2 }
+### Step 2 { #step2 }
 
 ![](./imgs/HVSR-2.png)
 
-### [Step 3](#step3) { #step3 }
+### Step 3 { #step3 }
 
 ![](./imgs/HVSR-3.png)
 
-### [Step 4](#step4) { #step4 }
+### Step 4 { #step4 }
 
 ![](./imgs/HVSR-4.png)
 
-### [Step 5](#step5) { #step5 }
+### Step 5 { #step5 }
 
 ![](./imgs/HVSR-5.png)
 
-### [Step 6](#step6) { #step6 }
+### Step 6 { #step6 }
 
 ![](./imgs/HVSR-6.png)
 
-### [Step 7](#step7) { #step7 }
+### Step 7 { #step7 }
 
 ![](./imgs/HVSR-7.png)
 

user-guide/docs/analysis/matlab.md

@@ -23,7 +23,7 @@ We provide two MATLAB applications in the Workspace:
 
 NOTE: Because MATLAB is an interactive program that you access in a GUI, you will not have the same responsiveness as running on your local laptop. We provide MATLAB as a convenience to interacting with your data in the Data Depot without having to download it to your local system, and also the version running on HPC resources is great for large datasets or heavy workloads that are too much for your laptop.
 
-### [How to Start a MATLAB Interactive Session in the Workspace](#start) { #start }
+### How to Start a MATLAB Interactive Session in the Workspace { #start }
 
 MATLAB that runs on VM
 
@@ -37,7 +37,7 @@ MATLAB that runs on VM
 	<li>Click Run to start your interactive session.</li>
 </ul>
 
-### [How to Submit a MATLAB Batch job in the Workspace](#submit) { #submit }
+### How to Submit a MATLAB Batch job in the Workspace { #submit }
 
 MATLAB Batch that runs on HPC
 

user-guide/docs/analysis/overview.md

@@ -1,14 +1,14 @@
 ## Analysis Applications
 
-### [Requesting New Applications](#newapps) { #newapps }
+### Requesting New Applications { #newapps }
 
 DesignSafe regularly adds new software applications in support of natural hazards engineering research. You may contact DesignSafe by submitting a help ticket if you would like to request the addition of a software application to the Workspace.
 
-### [Getting Your Own HPC Application](#software) { #software }
+### Getting Your Own HPC Application { #software }
 
 For those researchers with larger computational needs on the order of tens of thousands, or even millions of core-hours, or if you have a software application that we don't support in the web portal, you may request your own allocation of computing time on TACC's HPC systems. Your files can still be stored in the Data Depot, allowing you to share your research results with your team members, as well as curate and publish your findings.
 
-### [Commercial/Licensed Applications](#commercial) { #commercial }
+### Commercial/Licensed Applications { #commercial }
 
 The DesignSafe infrastructure includes support for commercial/licensed software. Wile in some cases licenses can be provided by the DesignSafe project itself, not all vendors will make licenses available for larger open communities at reasonable cost. You may contact DesignSafe by submitting a help ticket if you have questions regarding a commercial software application.
 

user-guide/docs/analysis/swbatch.md

@@ -14,7 +14,7 @@ Vantassel, J.P., Cox, B.R., (2020). SWinvert: A workflow for performing rigorous
 
 <em>Note: For software, version specific citations should be preferred to general concept citations, such as that listed above. To generate a version specific citation for <code>SWbatch</code>, please use the citation tool for that specific version on the <code>SWbatch</code> <a href="https://zenodo.org/badge/latestdoi/240935736" rel="nofollow">archive</a>.</em>
 
-### [Getting Started](#start) { #start } 
+### Getting Started { #start } 
 
 There are two ways of using <code>SWbatch</code>:
 
@@ -23,7 +23,7 @@ There are two ways of using <code>SWbatch</code>:
 	<li>Or directly through the DesignSafe-CI Research Workbench.</li>
 </ol>
 
-#### [Instructions for using the Jupyter Workflow](#start-jupyter) { #start-jupyter } 
+#### Instructions for using the Jupyter Workflow { #start-jupyter } 
 
 <ol>
 	<li>Visit the <code>SWprepost</code> <a href="https://github.com/jpvantassel/swprepost">GitHub</a> and follow the <code>Getting Started</code> instructions. The advanced example walks you through using the <code>SWinvert</code> surface wave inversion Jupyter workflow. (30 minutes)</li>
@@ -32,7 +32,7 @@ There are two ways of using <code>SWbatch</code>:
 	<li>Enjoy!</li>
 </ol>
 
-#### [Instructions for using the DesignSafe-CI Research Workbench](#start-ds) { #start-ds } 
+#### Instructions for using the DesignSafe-CI Research Workbench { #start-ds } 
 
 <ol>
 	<li>Visit the <code>SWprepost</code> <a href="https://github.com/jpvantassel/swprepost">GitHub</a> and follow the <code>Getting Started</code> instructions. This will introduce you to <code>SWprepost</code> and the <code>SWinvert</code> workflow, which is required before proceeding to step 2 in these instructions. (30 minutes)</li>

user-guide/docs/css/ds-docs.css

@@ -21,6 +21,16 @@
     --global-color-accent--xxx-dark: var(--color-accent-1-dark-3x);
 }
 
+/* To also support underlining headings in hovered card for `.h1` et cetera */
+/* https://github.com/DesignSafe-CI/DS-User-Guide/blob/df64c11/user-guide/docs/usecases/overview.md?plain=1#L34-L37 */
+/* https://github.com/TACC/Core-Styles/blob/v2.27.0/src/lib/_imports/components/c-card--docs.css#L23-L29 */
+[class*=card--]:hover :is( .h1, .h2, .h3, .h4, .h5, .h6 ) {
+    text-decoration-line: underline;
+    text-decoration-style: solid;
+    text-decoration-thickness: var(--global-border-width--normal);
+    text-underline-offset: .2em;
+}
+
 
 
 /* TACC-DOCS */
@@ -105,3 +115,24 @@ hr.spacer {
 [data-page-name$="usecases/overview.md"] .wy-nav-content {
   padding-bottom: 0; /* undo theme.css */
 }
+
+/* To hide anchor link for deeper headings */
+:is(h4, h5, h6) .headerlink {
+  display: none;
+}
+
+/* To write "DESIGNSAFE" like its logo */
+/* FAQ: To use, write `# <u><b>Design</b>Safe</u>` */
+:where(h1, h2, h3, h4, h5, h6) > u {
+  text-transform: uppercase;
+  text-decoration: none;
+  font-weight: var(--medium);
+  color: #565656;
+
+  /* To use DesignSafe logo font */
+  font-family: Futura; /* WARNING: requires user have this font installed */
+}
+:where(h1, h2, h3, h4, h5, h6) > u > b {
+  color: #cb463f;
+  font-weight: var(--black);
+}