[docathon] vale clean-up pass #1 (#24180)

## Summary & Motivation

- Fixes linting errors thrown by Vale (36 errors remain, but many are
TODOs or false-positives)

## How I Tested These Changes

- Running `vale` locally

## Changelog [New | Bug | Docs]

NOCHANGELOG

docs/.vale.ini

@@ -26,11 +26,33 @@ mdx = md
 #    FORMAT-SPECIFIC   #
 ########################
 
-[*.{md,mdx,rst}]
-# Rules in this section are enforced in all md, mdx, and rst files
-
 [*.{md,mdx,rst}]
 BasedOnStyles = Dagster, Terms, Vale
 
-; Ignore all :py directives
-IgnorePatterns = (:py:[^`]+`[^`]+`)
+; References:
+; - https://vale.sh/docs/topics/scoping/#non-standard-markup
+; - https://github.com/errata-ai/vale/blob/871dafd1e24500cee9d8ad82b25d42a136bb2103/testdata/fixtures/patterns/_vale#L14
+
+; Pattern     : (\\\{[^\n]+\})
+; Regex101    : https://regex101.com/r/GOx8Z6/2
+; Description : Ignore heading anchor renames
+
+; Description : Ignore code snippets
+; Pattern     : (`[^\n^`]+`)
+; Regex101    : https://regex101.com/r/c5EE6S/1
+
+; Pattern     : \[.*\](\(.*\))
+; Regex101    : https://regex101.com/r/GOx8Z6/3
+; Description : Ignore link HREFs
+
+; Additionally, we include TokenIgnores of `<TabItem>` and `<Tabs>` to strip these HTML elements,
+; because when these wrap markdown it causes the markdown linting to fail. For example, code blocks
+; within a tab item.
+
+TokenIgnores = (`[^`]*`), \
+    (\[.*\]\([^)]+\)), \
+    (\\\{[^}]+\}), \
+    (<\/?TabItem.*>), \
+    (<\/?Tabs.*>), \
+    (</?details>), \
+    (<summary>.*<\/summary>)

docs/docs-beta/docs/about/community.md

@@ -21,7 +21,7 @@ Dagster itself, defined as the code and intellectual property in the [Dagster pu
 
 ### Our pledge
 
-As members, contributors, and core team members, we pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+As members, contributors, and core team members, we pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible, or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
 
 We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
 
@@ -45,9 +45,9 @@ Examples of unacceptable behavior include:
 
 ### Slack content guidelines
 
-The Dagster core team will do its best to respond to every message but can't guarantee a response to everyone. Please don't treat the community as your own personal customer support service.
+The Dagster core team will do its best to respond to every message but can't guarantee a response to everyone. Don't treat the community as your own personal customer support service.
 
-Community members are expected to follow the guidelines for discussion in the Dagster community. Please make an effort to contribute quality content so that our community can spend more time hanging out and talking about issues rather than cleaning and filtering our communication channels.
+Community members are expected to follow the guidelines for discussion in the Dagster community. Make an effort to contribute quality content so that our community can spend more time hanging out and talking about issues rather than cleaning and filtering our communication channels.
 
 - Start discussions in the [right channels](https://app.slack.com/client/TCDGQDUKF/browse-channels)
 - Craft questions with sufficient detail to reproduce issues or address any concerns
@@ -79,12 +79,12 @@ The Dagster core team will follow these Community Impact Guidelines in determini
 | Level | Community impact | Consequence |
 |---|----|----|
 | Reminder | Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. | A private, written reminder from the Dagster core team, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. |
-| Warning | A violation through a single incident or series of actions. | A warning with consequencyarn lints for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces and external channels like social media. Violating these terms will lead to a permanent ban. |
+| Warning | A violation through a single incident or series of actions. | A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces and external channels like social media. Violating these terms will lead to a permanent ban. |
 | Permanent ban | Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. | A permanent ban from any sort of public interaction within the community. |
 
 ### Attribution
 
-- This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.0, available [here](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html).
+- This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.0, available at: [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html).
 - Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
 - Content Guidelines were inspired by [Discourse's FAQ for public discussion](https://meta.discourse.org/faq) and [dbt's Rules of the Road](https://docs.getdbt.com/docs/contributing/slack-rules-of-the-road).
-- For answers to common questions about this code of conduct, see the [Contributor Covenant FAQ](https://www.contributor-covenant.org/faq). Translations are available [here](https://www.contributor-covenant.org/translations).
+- For answers to common questions about this code of conduct, see the [Contributor Covenant FAQ](https://www.contributor-covenant.org/faq), or the [Contributor Covenant Translations](https://www.contributor-covenant.org/translations).

docs/docs-beta/docs/dagster-plus/access/authentication/azure-ad-sso.md

@@ -21,7 +21,7 @@ To complete the steps in this guide, you'll need:
 
 </details>
 
-## Step 1: Add the Dagster+ app in Azure AD \{#dagster-app}
+## Step 1: add the Dagster+ app in Azure AD \{#dagster-app}
 
 In this step, you'll add the Dagster+ app to your list of managed SaaS apps in Azure AD.
 
@@ -32,7 +32,7 @@ In this step, you'll add the Dagster+ app to your list of managed SaaS apps in A
 5. In the **Add from the gallery** section, type **Dagster+** in the search box.
 6. Select **Dagster+** from the results panel and then add the app. Wait a few seconds while the app is added to your tenant.
 
-## Step 2: Configure SSO in Azure AD \{#configure-sso}
+## Step 2: configure SSO in Azure AD \{#configure-sso}
 
 In this step, you'll configure and enable SSO for Azure AD in your Azure portal.
 
@@ -65,7 +65,7 @@ In this step, you'll configure and enable SSO for Azure AD in your Azure portal.
 
     When prompted, save the SAML metadata file to your computer.
 
-## Step 3: Upload the SAML metadata to Dagster+ \{#upload-saml}
+## Step 3: upload the SAML metadata to Dagster+ \{#upload-saml}
 
 After you've downloaded the SAML metadata file, upload it to Dagster+ using the `dagster-cloud` CLI:
 
@@ -75,7 +75,7 @@ dagster-cloud organization settings saml upload-identity-provider-metadata <path
    --url https://<organization_name>.dagster.cloud
 ```
 
-## Step 4: Create a test user \{#test-user}
+## Step 4: create a test user \{#test-user}
 
 In this section, you'll create a test user in the Azure portal.
 
@@ -92,4 +92,4 @@ import TestSSO from '../../../partials/\_TestSSO.md';
 
 <TestSSO />
 
-Click **Test this application** in the Azure portal. If successful, you'll be automatically signed into your Dagster+ organization.
+Click **Test this application** in the Azure portal. If successful, you'll be automatically signed into your Dagster+ organization.

docs/docs-beta/docs/dagster-plus/access/authentication/pingone-sso.md

@@ -49,7 +49,7 @@ To complete the steps in this guide, you'll need:
     2. When finished, click **Save and Continue.**
 2.  In the **Configure SAML** page:
     1.  Fill in the following:
-        - **ACS URLS** and **Entity ID**: Copy and paste the following URL, replacing `<organization_name>` with your Dagster+ organization name:
+        - **ACS URLs** and **Entity ID**: Copy and paste the following URL, replacing `<organization_name>` with your Dagster+ organization name:
 
            ```
            https://<organization_name>.dagster.cloud/auth/saml/consume

docs/docs-beta/docs/dagster-plus/access/rbac/users.md

@@ -42,13 +42,13 @@ After the user is created, you can [add the user to teams and assign user roles
 
 After a user is created, the **Manage user permissions** window will automatically display. You can also access this window by clicking **Edit** next to a user in the users table.
 
-TODO: Add picture previously at "/images/dagster-cloud/user-token-management/manage-new-user-permissions.png"
+{/* TODO: Add picture previously at "/images/dagster-cloud/user-token-management/manage-new-user-permissions.png" */}
 
 ### Adding users to teams
 
 Using the **Teams** field, you can add users to one or more teams. This is useful for centralizing permission sets for different types of users. Refer to the [Managing teams](/dagster-plus/access/rbac/teams) guide for more info about creating and managing teams.
 
-TODO: Add picture previously at "/images/dagster-cloud/user-token-management/add-user-to-teams.png
+{/* TODO: Add picture previously at "/images/dagster-cloud/user-token-management/add-user-to-teams.png */}
 
 **Note**: When determining a user's level of access, Dagster+ will use the **most permissive** role assigned to the user between all of their team memberships and any individual role grants. Refer to the [Managing user roles and permissions](/dagster-plus/access/rbac/user-roles-permissions) guide for more info.
 
@@ -89,4 +89,4 @@ Removing a user removes them from the organization. **Note**: If using a SAML-ba
 - Learn more about role-based access control (RBAC) in [Understanding User Roles & Permissions](/dagster-plus/access/rbac/user-roles-permissions)
 - Learn more about how to manage teams in Dagster+ in [Understanding Team Management in Dagster+](/dagster-plus/access/rbac/teams)
 - Learn more about SCIM provisioning in [Understanding SCIM Provisioning](/dagster-plus/access/authentication/scim-provisioning)
-- Learn more about authentication in [Understanding Authentication](/dagster-plus/access/authentication)
+- Learn more about authentication in [Understanding Authentication](/dagster-plus/access/authentication)

docs/docs-beta/docs/dagster-plus/deployment/branch-deployments/setting-up-branch-deployments.md

@@ -249,7 +249,7 @@ The last step is to verify that the GitHub Action runs successfully.
   </TabItem>
   <TabItem value="gitlab" label="GitLab">
 
-### Step 4.1: Add GitLab CI/CD script to your project
+### Step 4.1: add GitLab CI/CD script to your project
 
 :::note
 If you used the GitLab app to configure you're repository, this step isn't required. [Skip ahead to Step 4.5](#step-45-verify-gitlab-pipeline-runs)
@@ -263,7 +263,7 @@ Copy the following files to your project, and **replace** all references to `qui
 
 In the next step, you'll modify these files to work with your Dagster+ setup.
 
-### Step 4.2: Add the agent registry to dagster_cloud.yaml
+### Step 4.2: add the agent registry to dagster_cloud.yaml
 
 :::note
 If you used the GitLab app to configure you're repository, this step isn't required. [Skip ahead to Step 4.5](#step-45-verify-gitlab-pipeline-runs)
@@ -276,7 +276,7 @@ For example:
 
 <CodeExample filePath="dagster-plus/deployment/branch-deployments/dagster_cloud.yaml" language="yaml" />
 
-### Step 4.3: Configure GitLab CI/CD variables
+### Step 4.3: configure GitLab CI/CD variables
 
 :::note
 If you used the GitLab app to configure you're repository, this step isn't required. [Skip ahead to Step 4.5](#step-45-verify-gitlab-pipeline-runs)
@@ -330,7 +330,7 @@ Repeat steps 3-6 for each of the secrets required for your registry type:
 
 </Tabs>
 
-### Step 4.4: Configure GitLab CI/CD script
+### Step 4.4: configure GitLab CI/CD script
 
 :::note
 If you used the GitLab app to configure you're repository, this step isn't required. [Skip ahead to Step 4.5](#step-45-verify-gitlab-pipeline-runs)
@@ -350,7 +350,7 @@ build-image:
 
 Save and commit the files to the project.
 
-### Step 4.5: Verify GitLab pipeline runs
+### Step 4.5: verify GitLab pipeline runs
 
 The last step is to verify that the GitLab pipeline runs successfully.
 

docs/docs-beta/docs/dagster-plus/deployment/code-locations.md

@@ -98,8 +98,8 @@ To get started, review the appropriate example repository and then create your G
 
 - [GitHub repository with Dagster+ Serverless](https://github.com/dagster-io/dagster-cloud-serverless-quickstart/)
 - [GitHub repository with Dagster+ Hybrid](https://github.com/dagster-io/dagster-cloud-hybrid-quickstart/)
-- [Gitlab CI/CD for Dagster+ Serverless](https://github.com/dagster-io/dagster-cloud-action/blob/main/gitlab/serverless-ci.yml)
-- [Gitlab CI/CD for Dagster+ Hybrid](https://github.com/dagster-io/dagster-cloud-action/blob/main/gitlab/hybrid-ci.yml)
+- [GitLab CI/CD for Dagster+ Serverless](https://github.com/dagster-io/dagster-cloud-action/blob/main/gitlab/serverless-ci.yml)
+- [GitLab CI/CD for Dagster+ Hybrid](https://github.com/dagster-io/dagster-cloud-action/blob/main/gitlab/hybrid-ci.yml)
 
 
 Overall, the Git repository should contain:
@@ -133,7 +133,7 @@ Overall, the Git repository should contain:
         package_name: quickstart
     ```
 
-3. A CI/CD workflow file that contains the steps for adding your code location. These are the same steps outlined in the preceding section. Here is a minimal example workflow file for a Dagster+ Hybrid organization based on [this Gitlab template](https://github.com/dagster-io/dagster-cloud-action/blob/main/gitlab/hybrid-ci.yml).
+3. A CI/CD workflow file that contains the steps for adding your code location. These are the same steps outlined in the preceding section. Here is a minimal example workflow file for a Dagster+ Hybrid organization based on [this GitLab template](https://github.com/dagster-io/dagster-cloud-action/blob/main/gitlab/hybrid-ci.yml).
 
     ```yaml
     variables:
@@ -236,4 +236,4 @@ The monorepo should have CI/CD configured to deploy your changes and add or upda
 ## Next steps
 
 - After adding a code location, you may want to setup access controls
-- You may want to add additional configuration to your code location. This configuration will vary by agent type, but see examples for [setting default resource limits for Kubernetes](/dagster-plus/deployment/hybrid/agents/kubernetes) or [changing the IAM role for ECS](/todo).
+- You may want to add additional configuration to your code location. This configuration will vary by agent type, but see examples for [setting default resource limits for Kubernetes](/dagster-plus/deployment/hybrid/agents/kubernetes) or [changing the IAM role for ECS](/todo).

docs/docs-beta/docs/dagster-plus/deployment/code-locations/code-location-history.md

@@ -31,7 +31,7 @@ Before continuing, you should be familiar with:
 
 ![Screenshot highlighting the "Updated" column for a code location](/img/placeholder.svg)
 
-This will bring up a modal showing a history of every time that code location has been loaded, and metadata associated with that load. If you have connected Dagster+ to a GitHub or Gitlab repository, each row will have a link to the commit that was deployed at that point in time.
+This will bring up a modal showing a history of every time that code location has been loaded, and metadata associated with that load. If you have connected Dagster+ to a GitHub or GitLab repository, each row will have a link to the commit that was deployed at that point in time.
 
 If a code location has been deployed multiple times with identical metadata, these rows will be collapsed together. You can expand them by deselecting **Collapse similar entries** in the top left corner of the modal.
 

docs/docs-beta/docs/dagster-plus/deployment/environment-variables/dagster-ui.md

@@ -41,7 +41,9 @@ Before you begin, use the deployment switcher to select the right deployment.
     - **Code Location Scope** - select the code location(s) where the variable should be accessible. At least one code location is required.
 
 
-    ![TODO](/img/placeholder.svg)
+{/* TODO replace placeholder image */}
+
+![Screenshot of adding environment variables](/img/placeholder.svg)
 
 3. Click **Save**
 

docs/docs-beta/docs/dagster-plus/deployment/hybrid/agents/kubernetes.md

@@ -20,7 +20,7 @@ You'll also need access to a container registry to which you can push images and
 
 We recommend installing the Dagster+ agent using [Helm](https://helm.sh).
 
-## Step 1: Create a Kubernetes namespace
+## Step 1: create a Kubernetes namespace
 
 ```shell
 kubectl create namespace dagster-cloud
@@ -113,11 +113,11 @@ helm --namespace dagster-cloud upgrade agent \
     --values ./values.yaml
 ```
 
-## Troubleshooting Tips
+## Troubleshooting tips
 
 You can see basic health information about your agent in the Dagster+ UI:
 
-TODO: Screenshot
+{/* TODO: Screenshot */}
 
 ### View logs
 

docs/docs-beta/docs/dagster-plus/deployment/hybrid/architecture.md

@@ -49,9 +49,9 @@ All user code runs within your environment, in isolation from Dagster system cod
 
 ## The agent
 
-Because the agent communicates with the Dagster+ control plane over the agent API, it’s possible to support agents that operate in arbitrary compute environments.
+Because the agent communicates with the Dagster+ control plane over the agent API, it's possible to support agents that operate in arbitrary compute environments.
 
-This means that over time, Dagster+’s support for different user deployment environments will expand and custom agents can take advantage of bespoke compute environments such as HPC.
+This means that over time, Dagster+'s support for different user deployment environments will expand and custom agents can take advantage of bespoke compute environments such as HPC.
 
 Refer to the [Agents documentation](/todo) for more info, including the agents that are currently supported.
 

docs/docs-beta/docs/dagster-plus/deployment/serverless/runtime-environment.md

@@ -49,7 +49,7 @@ When possible, you should add dependencies by including the corresponding Python
 When adding dependencies with the `setup.py` file isn't possible, you can build a custom base image:
 
 :::note
-Setting a custom base image is not supported for GitLab CI/CD workflows out of the box, but you can write a custom GitLab CI/CD yaml file that implements the manual steps noted.
+Setting a custom base image isn't supported for GitLab CI/CD workflows out of the box, but you can write a custom GitLab CI/CD yaml file that implements the manual steps noted.
 :::
 
 1. Include `dagster-cloud[serverless]` as a dependency in your Docker image by adding the following line to your `Dockerfile`:
@@ -99,6 +99,7 @@ If you want to include the data folder, modify your `setup.py` to add the `packa
 <CodeExample filePath="dagster-plus/deployment/serverless/runtime-environment/data_files_setup.py" language="Python" title="Loading data files in setup.py" />
 
 ## Disable PEX deploys \{#disable-pex}
+
 Prior to using PEX files, Dagster+ deployed code using Docker images. This feature is still available.
 
 You can disable PEX in your GitHub or GitLab workflow, or by using the `dagster-cloud` CLI.
@@ -163,4 +164,4 @@ Setting a custom base image isn't supported for GitLab CI/CD workflows out of th
     </Tabs>
 </TabItem>
 
-</Tabs>
+</Tabs>

docs/docs-beta/docs/dagster-plus/getting-started/code-requirements.md

@@ -26,7 +26,7 @@ To work with Dagster+, your Dagster code:
 
 - **Must run in an environment where the `dagster` and `dagster-cloud` 0.13.2 or later Python packages are installed.**
 
-Additionally, note that:
+**Note**:
 
 - Different code locations can use different versions of Dagster
 - Dagster+ doesn't require a [`workspace.yaml` file](/todo). You can still create a `workspace.yaml` file to load your code in an open source Dagster webserver instance, but doing so won't affect how your code is loaded in Dagster+.