Skip to content

Cleanup mkdocs warning. #293

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ajfloeder merged 1 commit into from
Sep 25, 2025
Merged

Cleanup mkdocs warning. #293

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .markdownlint.jsonc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
50 changes: 29 additions & 21 deletions docs/guides/user-interactions/readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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 | |
Expand Down
4 changes: 3 additions & 1 deletion mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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;'
Expand Down
27 changes: 27 additions & 0 deletions overrides/stylesheets/extra.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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%;
}