From 7142973d1a3feeccbaa18fcd68bb3716f046b03f Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Tue, 22 Oct 2024 13:37:24 -0400 Subject: [PATCH] Make the Vale prose linter required As of Vale 3.8.0, it is possible to set custom comment delimiters so an author can temporarily disable a style rule within an MDX docs page. For example, an author can ignore the `protocol-products` rule by including this: ```text {/* vale messaging.protocol-products = NO */} This paragraph is about server access. {/* vale messaging.protocol-products = YES */} ``` As a result, we can require the Vale prose linter without worrying about false positives. This change updates the version of Vale used by the linting job to 3.8.0. It also makes the prose linting step part of the required Lint (Docs) job. To do so, it overrides `yarn git-update` to ignore submodules, checks out `gravitational/teleport` at the current branch, and copies the `teleport` clone into the directory where the docs engine expects submodules. It then edits the working directory of the Vale job. Since the Vale job only ran on `pull_request` events, and not `merge_group`, this change also adjusts all of `Lint (Docs)` to run on `pull_request`. Finally, this change edits the level of some Vale styles: - `error` (which causes Vale to exit with a nonzero status code): styles where we want to ensure consistency/correctness, and where it is possible to disable the style using comments. - `warning` (which causes Vale to print a message but exit with a zero status code): style rules that an author might need to ignore. This includes style rules with the `raw` scope, which cannot be disabled using comments. --- .github/workflows/doc-tests.yaml | 71 ++++++++----------- docs/.vale.ini | 1 + .../3rd-party-products/aws-vs-amazon.yml | 3 +- .../examples/teleport-accounts.yml | 4 +- docs/vale-styles/messaging/edition-names.yml | 10 +-- .../messaging/subjective-terms.yml | 4 +- .../vale-styles/structure/architecture-h2.yml | 2 +- .../vale-styles/structure/intro-paragraph.yml | 2 +- docs/vale-styles/structure/step-numbering.yml | 2 +- 9 files changed, 39 insertions(+), 60 deletions(-) diff --git a/.github/workflows/doc-tests.yaml b/.github/workflows/doc-tests.yaml index 8d0fdbb3491da..2a622ee0a26a6 100644 --- a/.github/workflows/doc-tests.yaml +++ b/.github/workflows/doc-tests.yaml @@ -39,13 +39,20 @@ jobs: permissions: contents: read + pull-requests: read steps: - name: Checkout uses: actions/checkout@v4 with: - repository: "gravitational/docs" - path: "docs" + repository: 'gravitational/teleport' + path: 'teleport' + + - name: Checkout + uses: actions/checkout@v4 + with: + repository: 'gravitational/docs' + path: 'docs' # Cache node_modules. Unlike the example in the actions/cache repo, this # caches the node_modules directory instead of the yarn cache. This is @@ -69,6 +76,7 @@ jobs: run: yarn install - name: Prepare docs site configuration + working-directory: docs # The environment we use for linting the docs differs from the one we # use for the live docs site in that we only test a single version of # the content. @@ -83,63 +91,40 @@ jobs: # of gravitational/teleport. We override this in order to build only a # single version of the docs. run: | - if [ $GITHUB_EVENT_NAME = "pull_request" ]; then - BRANCH=$GITHUB_HEAD_REF; - elif [ $GITHUB_EVENT_NAME = "merge_group" ]; then - # GitHub populates $GITHUB_REF with: - # refs/heads/gh-readonly-queue//pr-- - # - # We strip the "refs/heads/" prefix so we can check out the branch. - BRANCH=$(echo $GITHUB_REF | sed -E "s|refs/heads/(.*)|\1|") - else - echo "Unexpected event name: $GITHUB_EVENT_NAME"; - exit 1; - fi - - cd $GITHUB_WORKSPACE/docs echo "" > .gitmodules rm -rf content/* cd content - # Add a submodule at docs/content/teleport - git submodule add --force -b $BRANCH -- https://github.com/gravitational/teleport + # Rather than using a submodule, copy the teleport source into the + # content directory. + cp -r $GITHUB_WORKSPACE/teleport $GITHUB_WORKSPACE/docs/content cd $GITHUB_WORKSPACE/docs - echo "{\"versions\": [{\"name\": \"teleport\", \"branch\": \"$BRANCH\", \"deprecated\": false}]}" > $GITHUB_WORKSPACE/docs/config.json + echo "{\"versions\": [{\"name\": \"teleport\", \"branch\": \"teleport\", \"deprecated\": false}]}" > $GITHUB_WORKSPACE/docs/config.json + cat <<< "$(jq '.scripts."git-update" = "echo Skipping submodule update"' package.json)" > package.json yarn build-node - name: Check spelling - run: cd $GITHUB_WORKSPACE/docs && yarn spellcheck content/teleport - - - name: Lint the docs - run: cd $GITHUB_WORKSPACE/docs && yarn markdown-lint - - - name: Test the docs build - working-directory: docs - run: yarn build + working-directory: 'docs' + run: yarn spellcheck content/teleport - stylecheck: - name: Lint docs prose style - runs-on: ubuntu-latest - needs: changes - if: ${{ !startsWith(github.head_ref, 'dependabot/') && needs.changes.outputs.changed == 'true' && github.event_name == 'pull_request' }} - permissions: - pull-requests: read - steps: - - name: Check out the teleport repo - uses: actions/checkout@v4 - with: - repository: "gravitational/teleport" + - name: Lint docs formatting + working-directory: 'docs' + run: yarn markdown-lint - - name: Run the linter + - name: Lint docs prose uses: errata-ai/vale-action@d89dee975228ae261d22c15adcd03578634d429c # v2.1.1 with: - version: 2.30.0 + version: 3.9.0 # Take the comma-separated list of files returned by the "Check for # relevant changes" job. - separator: "," + separator: ',' + workdir: '${{ github.workspace }}/docs/content/teleport' files: ${{ needs.changes.outputs.changed_files }} # Restrict the linter to lines modified/added by a PR, not entire # changed files. filter_mode: added fail_on_error: true - vale_flags: "--config=docs/.vale.ini" + vale_flags: '--config=${{ github.workspace }}/docs/content/teleport/docs/.vale.ini' + - name: Test the docs build + working-directory: 'docs' + run: yarn build diff --git a/docs/.vale.ini b/docs/.vale.ini index 9620898c3adba..024986fb2b30a 100644 --- a/docs/.vale.ini +++ b/docs/.vale.ini @@ -6,3 +6,4 @@ mdx = md [*.md] BasedOnStyles = messaging,examples,3rd-party-products,structure +CommentDelimiters = "{/*,*/}" diff --git a/docs/vale-styles/3rd-party-products/aws-vs-amazon.yml b/docs/vale-styles/3rd-party-products/aws-vs-amazon.yml index c52b383736a42..ed6ede32b8bcc 100644 --- a/docs/vale-styles/3rd-party-products/aws-vs-amazon.yml +++ b/docs/vale-styles/3rd-party-products/aws-vs-amazon.yml @@ -15,8 +15,7 @@ # /^AWS /{ print gensub(/AWS (.*)/," \"Amazon \\1\"","1") ": " $0}' extends: substitution message: "Incorrect AWS product name. Use %s instead of %s." -scope: raw -level: warning +level: error ignorecase: true swap: "Amazon Account Management": AWS Account Management diff --git a/docs/vale-styles/examples/teleport-accounts.yml b/docs/vale-styles/examples/teleport-accounts.yml index 1b487a3398dee..dd5d49e21136b 100644 --- a/docs/vale-styles/examples/teleport-accounts.yml +++ b/docs/vale-styles/examples/teleport-accounts.yml @@ -1,8 +1,8 @@ extends: substitution message: "Incorrect example of a Teleport account URL. Use %s instead of %s." -level: error +scope: raw # So we can catch instances in code fences +level: warning scope: - - raw ignorecase: true swap: - 'https://(?!status|example)\w+.teleport\.sh': 'example.teleport.sh (or status.teleport.sh for the status page)' diff --git a/docs/vale-styles/messaging/edition-names.yml b/docs/vale-styles/messaging/edition-names.yml index 398f678aeb30f..dedec1ee059ad 100644 --- a/docs/vale-styles/messaging/edition-names.yml +++ b/docs/vale-styles/messaging/edition-names.yml @@ -1,13 +1,7 @@ extends: existence scope: - # Using the raw scope so we can catch instances in TabItem labels. - - raw message: '"%s" is no longer a recognized Teleport edition. Use "Teleport Enterprise (Self-Hosted)" or "Teleport Enterprise (Cloud)" instead. If the hosting type is not important in a given sentence, there is no need to specify it, and you can use "Teleport Enterprise".' level: error -ignorecase: false +ignorecase: true tokens: - # Adding the pattern '[ \t]*\n?[ \t]*' between each word since we are using the raw - # scope. This lets use catch violations that span two lines (i.e., that occupy - # the same paragraph). - - 'Teleport[ \t]*\n?[ \t]*Cloud' - - 'Teleport[ \t]*\n?[ \t]*Enterprise[ \t]*\n?[ \t]*Cloud' + - 'Teleport Enterprise Cloud' diff --git a/docs/vale-styles/messaging/subjective-terms.yml b/docs/vale-styles/messaging/subjective-terms.yml index 4e41d520e31f2..b5b79b9b13af8 100644 --- a/docs/vale-styles/messaging/subjective-terms.yml +++ b/docs/vale-styles/messaging/subjective-terms.yml @@ -1,7 +1,7 @@ extends: existence link: "https://github.com/gravitational/docs/blob/main/docs-contributors/style-guide.md#voice" -message: "Avoid using '%s' as a qualifier, since it is subject to interpretation. Use more technically precise terms instead." -level: error +message: "Consider avoiding '%s' as a qualifier, since it is subject to interpretation. Use more technically precise terms instead." +level: warning ignorecase: true tokens: - "powerful(ly)?" diff --git a/docs/vale-styles/structure/architecture-h2.yml b/docs/vale-styles/structure/architecture-h2.yml index 4889bd4aaf96d..297571def5150 100644 --- a/docs/vale-styles/structure/architecture-h2.yml +++ b/docs/vale-styles/structure/architecture-h2.yml @@ -6,7 +6,7 @@ # This style defines a how-to guide as any guide that includes at least one H2 # beginning "Step [0-9]". extends: script -level: error +level: warning message: "In a how-to guide, the first H2-level section must be called `## How it works`. Use this section to include 1-3 paragraphs that describe the high-level architecture of the setup shown in the guide, i.e., which infrastructure components are involved and how they communicate. If there is already architectural information in the guide, include it in a `## How it works` section." scope: raw script: | diff --git a/docs/vale-styles/structure/intro-paragraph.yml b/docs/vale-styles/structure/intro-paragraph.yml index 3bee6806e4d66..1c34b054b2c2a 100644 --- a/docs/vale-styles/structure/intro-paragraph.yml +++ b/docs/vale-styles/structure/intro-paragraph.yml @@ -1,7 +1,7 @@ # This style enforces the presence of an introductory paragraph before the first # H2 of a docs page. extends: script -level: error +level: warning message: There must be a brief intro paragraph before the first H2-level section of a docs page. Use this to describe the purpose of the guide so a reader can determine whether they should continue reading. If the guide introduces a feature, describe the purpose and benefits of the feature. If there is already an "Introduction" H2 or similar, remove the heading. scope: raw script: | diff --git a/docs/vale-styles/structure/step-numbering.yml b/docs/vale-styles/structure/step-numbering.yml index ce5c584a84021..68ed257ab2b6b 100644 --- a/docs/vale-styles/structure/step-numbering.yml +++ b/docs/vale-styles/structure/step-numbering.yml @@ -6,7 +6,7 @@ # such as the presence of step headings in how-to guides and the formatting of # step headings. extends: script -level: error +level: warning message: Guides that include H2 sections named after numbered steps (e.g., "Step 1/5") must have the expected sequence of numbers and accurate total numbers of steps. This heading either has an unexpected step number or an unexpected total number of steps. scope: raw script: |