Cleanup mkdocs warning.

Adjust tables to prevent breaks in the Argument column of tables by adding a stylesheet.
user-interactions guide:
- cleanup markdown warnings in user-interactions guide.
- commonize language around profiles

Signed-off-by: Anthony Floeder <anthony.floeder@hpe.com>

Author: ajfloeder

.markdownlint.jsonc

@@ -18,6 +18,9 @@
     "code_block_line_length": 500  // some example console output is wide
   },
 
+  // MD024/no-duplicate-heading - No duplicate headings
+  "MD024": false,
+
   // MD046/code-block-style - Code block style
   // Disable consistency checks between fenced/indented code blocks.
   // Standard code blocks should use fences, while mkdocs admonitions require

docs/guides/user-interactions/readme.md

@@ -15,17 +15,18 @@ Once the job is running on compute nodes, the application can find access to Rab
 
 ### jobdw
 
-The `jobdw` directive command tells the Rabbit software to create a file system on the Rabbit hardware for the lifetime of the user's job. At the end of the job, any data that is not moved off of the file system either by the application or through a `copy_out` directive will be lost. Multiple `jobdw` directives can be listed in the same job script.
+The `jobdw` directive command tells the Rabbit software to create a file system on the Rabbit hardware for the lifetime of the user's job. At the end of the job, any data that is not moved off of the file system either by the application or through a `copy_out` directive is lost. Multiple `jobdw` directives can be listed in the same job script.
 
 #### Command Arguments
+
 | Argument | Required | Value | Notes |
 |----------|----------|-------|-------|
-| `type` | Yes | `raw`, `xfs`, `gfs2`, `lustre` | Type defines how the storage should be formatted. For Lustre file systems, a single file system is created that is mounted by all computes in the job. For raw, xfs, and GFS2 storage, a separate file system is allocated for each compute node. | 
+| `type` | Yes | `raw`, `xfs`, `gfs2`, `lustre` | Type defines how the storage should be formatted. For Lustre file systems, a single file system is created that is mounted by all computes in the job. For raw, xfs, and GFS2 storage, a separate file system is allocated for each compute node. |
 | `capacity` | Yes | Allocation size with units. `1TiB`, `100GB`, etc. | Capacity interpretation varies by storage type. For Lustre file systems, capacity is the aggregate OST capacity. For raw, xfs, and GFS2 storage, capacity is the capacity of the file system for a single compute node. Capacity suffixes are: `KB`, `KiB`, `MB`, `MiB`, `GB`, `GiB`, `TB`, `TiB` |
 | `name` | Yes | String including numbers and '-' | This is a name for the storage allocation that is unique within a job |
-| `profile` | No | Profile name | This specifies which profile to use when allocating storage. Profiles include `mkfs` and `mount` arguments, file system layout, and many other options. Profiles are created by admins. When no profile is specified, the default profile is used. More information about storage profiles can be found in the [Storage Profiles](../storage-profiles/readme.md) guide. |
+| `profile` | No | Profile name | This specifies which profile to use when allocating storage. Profiles include `mkfs` and `mount` arguments, file system layout, and many other options. When no profile is specified, the default profile is used. More information about storage profiles can be found in the [Storage Profiles](../storage-profiles/readme.md) guide. **Note:** Admins are responsible for profiles.|
 | `requires` | No | `copy-offload` | Use this option with [Copy Offload](../data-movement/copy-offload.md). This is for users who want to initiate data movement to or from the Rabbit storage from within their application. |
-| `requires` | No | `user-container-auth` | Use this option with [User Containers](../user-containers/readme.md) that have an application that expects to use the same kind of TLS certificate and [per-Workflow token](../data-movement/copy-offload.md#per-workflow-token) that is configured for [Copy Offload](../data-movement/copy-offload.md). |
+| `requires` | No | `user-container-auth` | Use this option with [User Containers](../user-containers/readme.md) that have an application that expects to use the same kind of TLS certificate and [per-Workflow token](../data-movement/copy-offload.md#wlm-and-the-per-workflow-token) that is configured for [Copy Offload](../data-movement/copy-offload.md). |
 
 #### Examples
 
@@ -52,12 +53,13 @@ This directive results in a 50GB GFS2 file system created for each compute node
 The `create_persistent` command results in a storage allocation on the Rabbit nodes that lasts beyond the lifetime of the job. This is useful for creating a file system that can share data between jobs. Only a single `create_persistent` directive is allowed in a job, and it cannot be in the same job as a `destroy_persistent` directive. See [persistentdw](readme.md#persistentdw) to utilize the storage in a job.
 
 #### Command Arguments
+
 | Argument | Required | Value | Notes |
 |----------|----------|-------|-------|
-| `type` | Yes | `raw`, `xfs`, `gfs2`, `lustre` | Type defines how the storage should be formatted. For Lustre file systems, a single file system is created. For raw, xfs, and GFS2 storage, a separate file system is allocated for each compute node in the job. | 
+| `type` | Yes | `raw`, `xfs`, `gfs2`, `lustre` | Type defines how the storage should be formatted. For Lustre file systems, a single file system is created. For raw, xfs, and GFS2 storage, a separate file system is allocated for each compute node in the job. |
 | `capacity` | Yes | Allocation size with units. `1TiB`, `100GB`, etc. | Capacity interpretation varies by storage type. For Lustre file systems, capacity is the aggregate OST capacity. For raw, xfs, and GFS2 storage, capacity is the capacity of the file system for a single compute node. Capacity suffixes are: `KB`, `KiB`, `MB`, `MiB`, `GB`, `GiB`, `TB`, `TiB` |
 | `name` | Yes | Lowercase string including numbers and '-' | This is a name for the storage allocation that is unique within the system |
-| `profile` | No | Profile name | This specifies which profile to use when allocating storage. Profiles include `mkfs` and `mount` arguments, file system layout, and many other options. Profiles are created by admins. When no profile is specified, the default profile is used. The profile used when creating the persistent storage allocation is the same profile used by jobs that use the persistent storage. More information about storage profiles can be found in the [Storage Profiles](../storage-profiles/readme.md) guide.|
+| `profile` | No | Profile name | This specifies which profile to use when allocating storage. Profiles include `mkfs` and `mount` arguments, file system layout, and many other options. When no profile is specified, the default profile is used. The profile used when creating the persistent storage allocation is the same profile used by jobs that use the persistent storage. More information about storage profiles can be found in the [Storage Profiles](../storage-profiles/readme.md) guide. **Note:** Admins are responsible for profiles.|
 
 #### Examples
 
@@ -74,32 +76,36 @@ This directive results in a 100GiB xfs file system created for each compute node
 This directive results in a single 10TiB Lustre file system being created that can be accessed later by any compute nodes in the system. Multiple jobs can access a Rabbit Lustre file system at the same time. This job can be scheduled with a single compute node (or zero compute nodes if the WLM allows), without any limitations on compute node counts for subsequent jobs using the persistent Lustre file system.
 
 ### destroy_persistent
-The `destroy_persistent` command will delete persistent storage that was allocated by a corresponding `create_persistent`. If the persistent storage is currently in use by a job, then the job containing the `destroy_persistent` command will fail. Only a single `destroy_persistent` directive is allowed in a job, and it cannot be in the same job as a `create_persistent` directive.
+
+The `destroy_persistent` command deletes persistent storage that was allocated by a corresponding `create_persistent`. If the persistent storage is currently in use by a job, then the job containing the `destroy_persistent` command fails. Only a single `destroy_persistent` directive is allowed in a job, and it cannot be in the same job as a `create_persistent` directive.
 
 #### Command Arguments
+
 | Argument | Required | Value | Notes |
 |----------|----------|-------|-------|
-| `name` | Yes | Lowercase string including numbers and '-' | This is a name for the persistent storage allocation that will be destroyed |
+| `name` | Yes | Lowercase string including numbers and '-' | This is a name for the persistent storage allocation that is destroyed |
 
 #### Examples
 
 ```bash
 #DW destroy_persistent name=shared-data
 ```
 
-This directive will delete the persistent storage allocation with the name `shared-data`
+This directive deletes the persistent storage allocation with the name `shared-data`
 
 ### persistentdw
+
 The `persistentdw` command makes an existing persistent storage allocation available to a job. The persistent storage must already be created from a `create_persistent` command in a different job script. Multiple `persistentdw` commands can be used in the same job script to request access to multiple persistent allocations.
 
 Persistent Lustre file systems can be accessed from any compute nodes in the system, and the compute node count for the job can vary as needed. Multiple jobs can access a persistent Lustre file system concurrently if desired. Raw, xfs, and GFS2 file systems can only be accessed by compute nodes that have a physical connection to the Rabbits hosting the storage, and jobs accessing these storage types must have the same compute node count as the job that made the persistent storage.
 
 #### Command Arguments
+
 | Argument | Required | Value | Notes |
 |----------|----------|-------|-------|
-| `name` | Yes | Lowercase string including numbers and '-' | This is a name for the persistent storage that will be accessed |
+| `name` | Yes | Lowercase string including numbers and '-' | This is a name for the persistent storage that is accessed |
 | `requires` | No | `copy-offload` | Use this option with [Copy Offload](../data-movement/copy-offload.md). This is for users who want to initiate data movement to or from the Rabbit storage from within their application. |
-| `requires` | No | `user-container-auth` | Use this option with [User Containers](../user-containers/readme.md) that have an application that expects to use the same kind of TLS certificate and [per-Workflow token](../data-movement/copy-offload.md#per-workflow-token) that is configured for [Copy Offload](../data-movement/copy-offload.md). |
+| `requires` | No | `user-container-auth` | Use this option with [User Containers](../user-containers/readme.md) that have an application that expects to use the same kind of TLS certificate and [per-Workflow token](../data-movement/copy-offload.md#wlm-and-the-per-workflow-token) that is configured for [Copy Offload](../data-movement/copy-offload.md). |
 
 #### Examples
 
@@ -111,14 +117,15 @@ This directive causes the `shared-data` persistent storage allocation to be moun
 
 ### copy_in/copy_out
 
-The `copy_in` and `copy_out` directives are used to move data to and from the storage allocations on Rabbit nodes. The `copy_in` directive requests that data be moved into the Rabbit file system before application launch, and the `copy_out` directive requests data to be moved off of the Rabbit file system after application exit. This is different from data-movement that is requested through the copy-offload API, which occurs during application runtime. Multiple `copy_in` and `copy_out` directives can be included in the same job script. More information about data movement can be found in the [Data Movement](../data-movement/readme.md) documentation.
+The `copy_in` and `copy_out` directives are used to move data to and from the storage allocations on Rabbit nodes. The `copy_in` directive requests that data be moved into the Rabbit file system before application launch, and the `copy_out` directive requests data to be moved off of the Rabbit file system after application exit. Multiple `copy_in` and `copy_out` directives can be included in the same job script. This is different from data-movement that is requested through the copy-offload API, which occurs during application runtime. More information about data movement can be found in the [Data Movement](../data-movement/readme.md) documentation.
 
 #### Command Arguments
-| Argument | Required | Value | Notes |
-|----------|----------|-------|-------|
+
+|Argument|Required|Value|Notes|
+|--------|----------|-------|-------|
 | `source` | Yes | `[path]`, `$DW_JOB_[name]/[path]`, `$DW_PERSISTENT_[name]/[path]` | `[name]` is the name of the Rabbit persistent or job storage as specified in the `name` argument of the `jobdw` or `persistentdw` directive. Any `'-'` in the name from the `jobdw` or `persistentdw` directive should be changed to a `'_'` in the `copy_in` and `copy_out` directive. |
 | `destination` | Yes | `[path]`, `$DW_JOB_[name]/[path]`, `$DW_PERSISTENT_[name]/[path]` | `[name]` is the name of the Rabbit persistent or job storage as specified in the `name` argument of the `jobdw` or `persistentdw` directive. Any `'-'` in the name from the `jobdw` or `persistentdw` directive should be changed to a `'_'` in the `copy_in` and `copy_out` directive. |
-| `profile` | No | Profile name | This specifies which profile to use when copying data. Profiles specify the copy command to use, MPI arguments, and how output gets logged. If no profile is specified then the default profile is used. Profiles are created by an admin. |
+| `profile` | No | Profile name | This specifies the profile to use when copying data. Profiles specify the copy command to use, MPI arguments, and how output is logged. If no profile is specified then the default profile is used. More information about datamovement profiles can be found in the [DataMovement Profiles](../data-movement/readme.md#data-movement-profiles) guide. **Note:** Admins are responsible for profiles.|
 
 #### Examples
 
@@ -156,13 +163,14 @@ This set of directives makes use of a persistent storage allocation and a job st
 The `container` directive is used to launch user containers on the Rabbit nodes. The containers have access to `jobdw`, `persistentdw`, or global Lustre storage as specified in the `container` directive. More documentation for user containers can be found in the [User Containers](../user-containers/readme.md) guide. Only a single `container` directive is allowed in a job.
 
 #### Command Arguments
+
 | Argument | Required | Value | Notes |
 |----------|----------|-------|-------|
 | `name` | Yes | Lowercase string including numbers and '-' | This is a name for the container instance that is unique within a job |
-| `profile` | Yes | Profile name | This specifies which container profile to use. The container profile contains information about which container to run, which file system types to expect, which network ports are needed, and many other options. An admin is responsible for creating the container profiles. |
-| `DW_JOB_[expected]` | No | `jobdw` storage allocation `name` | The container profile will list `jobdw` file systems that the container requires. `[expected]` is the name as specified in the container profile |
-| `DW_PERSISTENT_[expected]` | No | `persistentdw` storage allocation `name` | The container profile will list `persistentdw` file systems that the container requires. `[expected]` is the name as specified in the container profile |
-| `DW_GLOBAL_[expected]` | No | Global lustre path | The container profile will list global Lustre file systems that the container requires. `[expected]` is the name as specified in the container profile |
+| `profile` | Yes | Profile name | This specifies which container profile to use. The container profile contains information about which container to run, which file system types to expect, which network ports are needed, and many other options.  **Note:** Admins are responsible for profiles.|
+| `DW_JOB_[expected]` | No | `jobdw` storage allocation `name` | The container profile lists `jobdw` file systems that the container requires. `[expected]` is the name as specified in the container profile |
+| `DW_PERSISTENT_[expected]` | No | `persistentdw` storage allocation `name` | The container profile lists `persistentdw` file systems that the container requires. `[expected]` is the name as specified in the container profile |
+| `DW_GLOBAL_[expected]` | No | Global lustre path | The container profile lists global Lustre file systems that the container requires. `[expected]` is the name as specified in the container profile |
 
 #### Examples
 
@@ -179,8 +187,8 @@ The WLM makes a set of environment variables available to the job application ru
 
 | Environment Variable | Value | Notes |
 |----------------------|-------|-------|
-| `DW_JOB_[name]` | Mount path of a `jobdw` file system | `[name]` is from the `name` argument in the `jobdw` directive. Any `'-'` characters in the `name` will be converted to `'_'` in the environment variable. There will be one of these environment variables per `jobdw` directive in the job. |
-| `DW_PERSISTENT_[name]` | Mount path of a `persistentdw` file system | `[name]` is from the `name` argument in the `persistentdw` directive. Any `'-'` characters in the `name` will be converted to `'_'` in the environment variable. There will be one of these environment variables per `persistentdw` directive in the job. |
+| `DW_JOB_[name]` | Mount path of a `jobdw` file system | `[name]` is from the `name` argument in the `jobdw` directive. Any `'-'` characters in the `name` are converted to `'_'` in the environment variable. There is one of these environment variables per `jobdw` directive in the job. |
+| `DW_PERSISTENT_[name]` | Mount path of a `persistentdw` file system | `[name]` is from the `name` argument in the `persistentdw` directive. Any `'-'` characters in the `name` are converted to `'_'` in the environment variable. There is one of these environment variables per `persistentdw` directive in the job. |
 | `NNF_CONTAINER_PORTS` | Comma separated list of ports | These ports are used together with the IP address of the local Rabbit to communicate with a user container specified by a `container` directive. More information can be found in the [User Containers](../user-containers/readme.md) guide. |
 | `DW_WORKFLOW_NAME` | Name of the Workflow | |
 | `DW_WORKFLOW_NAMESPACE` | Namespace of the Workflow | |

mkdocs.yml

@@ -34,7 +34,7 @@ nav:
       - 'CRD Version Bumper': 'repo-guides/crd-bumper/readme.md'
       - 'Editing APIs': 'repo-guides/crd-bumper/editing-apis.md'
       - 'CRD Upgrade Helpers': 'repo-guides/release-nnf-sw/crd-upgrade-helpers.md'
-      - 'Upgrade Tester': 'repo-guides/release-nnf-sw/upgrade-tester.md'
+      - 'Upgrade Tester': 'repo-guides/testing/upgrade-tester.md'
 theme:
   name: 'material'
   custom_dir: overrides
@@ -51,6 +51,8 @@ theme:
     - search.share
   logo: img/logo.png
   favicon: img/logo.png
+extra_css:
+  - stylesheets/extra.css
 plugins:
   - search:
       separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'

overrides/stylesheets/extra.css

@@ -0,0 +1,27 @@
+/* Prevent word wrapping only in the first column (Argument) */
+.md-typeset table th:first-child,
+.md-typeset table td:first-child {
+    white-space: nowrap;
+    word-break: keep-all;
+    min-width: 120px;
+}
+
+/* Ensure code elements in the first column don't wrap */
+.md-typeset table th:first-child code,
+.md-typeset table td:first-child code {
+    white-space: nowrap;
+    word-break: keep-all;
+}
+
+/* Allow normal wrapping for other columns (especially Notes) */
+.md-typeset table th:not(:first-child),
+.md-typeset table td:not(:first-child) {
+    white-space: normal;
+    word-break: normal;
+}
+
+/* Keep table layout flexible */
+.md-typeset table {
+    table-layout: auto;
+    width: 100%;
+}