From c9e7e1d9984330c9383c9551463f87949961abc0 Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Mon, 23 Dec 2024 09:59:34 -0500 Subject: [PATCH] Edit docs CI workflows to accommodate Docusaurus Backports #48388 * Edit docs CI workflows to accommodate Docusaurus - Copy the `gravitational/teleport` source into the `content` directory of a `gravitational/docs-website` clone and overwrite the `git-update` yarn script with a no-op command. With way, we can use the `gravitational/teleport` clone across multiple workflow steps (e.g., the prose linting step), and can identify a branch to pull using the `actions/checkout` defaults. Name the submodule directory `current` to match the expectations of the Docusaurus site. - Remove the Vercel preview workflow. After the docs engine migration, we'll no longer need to deploy a preview to Vercel in order to show docs authors what their potential changes look like on a rendered docs site. Also fixes spelling errors caught by a later version of cspell. * Fix shellcheck issues in doc-tests.yaml script - Add `exit` commands for failed `cd`s - Don't read from and write to `package.json` in the same pipeline - Add double quotes around variables * Use latest Docusaurus site config schema * Fix the Prepare docs site configuration step - Remove unneeded `cd`s - Use the correct version name in the `config.json` prepared for the Docusaurus site --- .github/workflows/doc-tests.yaml | 62 ++++++++++++++---- .github/workflows/vercel-preview.yaml | 65 ------------------- docs/cspell.json | 8 +++ .../guides/connecting-apps.mdx | 7 +- docs/pages/reference/resources.mdx | 2 +- docs/pages/reference/signature-algorithms.mdx | 4 +- 6 files changed, 62 insertions(+), 86 deletions(-) delete mode 100644 .github/workflows/vercel-preview.yaml diff --git a/.github/workflows/doc-tests.yaml b/.github/workflows/doc-tests.yaml index 5030bebe367b1..d4d55c063e3ae 100644 --- a/.github/workflows/doc-tests.yaml +++ b/.github/workflows/doc-tests.yaml @@ -44,23 +44,54 @@ jobs: - 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-website' + 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 + # because yarn needs to build fresh packages even when it copies files + # from the yarn cache into node_modules. + # See: + # https://github.com/actions/cache/blob/main/examples.md#node---yarn + - uses: actions/cache@v4 + id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`) + with: + path: '${{ github.workspace }}/docs/node_modules' + key: ${{ runner.os }}-yarn-${{ hashFiles(format('{0}/docs/yarn.lock', github.workspace)) }} + restore-keys: | + ${{ runner.os }}-yarn- + + - name: Install docs site dependencies + working-directory: docs + if: ${{ steps.yarn-cache.outputs.cache-hit != 'true' }} + # Prevent occasional `yarn install` executions that run indefinitely + timeout-minutes: 10 + run: yarn install - name: Prepare docs site configuration # 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. # - # To do this, we replace the three submodules we use for building the - # live docs site with a single submodule, pointing to the - # gravitational/teleport branch we are linting. - # + # To do this, we delete the three submodules we use for building the + # live docs site and copy a gravitational/teleport clone into the + # content directory. + # # The docs engine expects a config.json file at the root of the # gravitational/docs clone that associates directories with git # submodules. By default, these directories represent versioned branches # of gravitational/teleport. We override this in order to build only a # single version of the docs. + # + # We also replace data fetched from Sanity CMS with hardcoded JSON + # objects to remove the need to authenticate with Sanity. Each includes + # the minimal set of data required for docs builds to succeed. run: | if [ $GITHUB_EVENT_NAME = "pull_request" ]; then BRANCH=$GITHUB_HEAD_REF; @@ -78,16 +109,19 @@ jobs: 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 - cd $GITHUB_WORKSPACE/docs - echo "{\"versions\": [{\"name\": \"teleport\", \"branch\": \"$BRANCH\", \"deprecated\": false}]}" > $GITHUB_WORKSPACE/docs/config.json - yarn install - yarn build-node + # Rather than using a submodule, copy the teleport source into the + # content directory. + cp -r "$GITHUB_WORKSPACE/teleport" "$GITHUB_WORKSPACE/docs/content/current" + jq -nr --arg version "current" '{"versions": [{"name": $version,"branch": $version,"deprecated": false,"isDefault": true}]}' > config.json + NEW_PACKAGE_JSON=$(jq '.scripts."git-update" = "echo Skipping submodule update"' package.json); + NEW_PACKAGE_JSON=$(jq '.scripts."prepare-sanity-data" = "echo Using pre-populated Sanity data"' <<< "$NEW_PACKAGE_JSON"); + echo "$NEW_PACKAGE_JSON" > package.json; + echo "{}" > data/events.json + echo '{"bannerButtons":{"second":{"title":"LOG IN","url":"https://teleport.sh"},"first":{"title":"Support","url":"https://goteleport.com/support/"}},"navbarData":{"rightSide":{},"logo":"/favicon.svg","menu":[]}}' > data/navbar.json - name: Check spelling - run: cd $GITHUB_WORKSPACE/docs && yarn spellcheck content/teleport + working-directory: 'docs' + run: yarn spellcheck content/current - name: Lint the docs run: cd $GITHUB_WORKSPACE/docs && yarn markdown-lint diff --git a/.github/workflows/vercel-preview.yaml b/.github/workflows/vercel-preview.yaml deleted file mode 100644 index f74b3086138c0..0000000000000 --- a/.github/workflows/vercel-preview.yaml +++ /dev/null @@ -1,65 +0,0 @@ ---- -name: Deploy Vercel Preview -permissions: - # Required in order to comment on PRs with a deployment link - pull-requests: write -env: - VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }} - VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }} - -on: - pull_request: - paths: - - 'docs/**' - - .github/workflows/vercel-preview.yaml - types: [opened, reopened, synchronize] - workflow_dispatch: - -jobs: - deploy-vercel-preview: - name: Deploy Vercel preview - runs-on: ubuntu-latest - environment: vercel - - steps: - - name: Extract branch name - run: echo "branch=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}" >> $GITHUB_OUTPUT - id: extract_branch - - uses: actions/checkout@v4 - with: - repository: 'gravitational/docs' - - name: Configure Submodules - env: - BRANCH: ${{ steps.extract_branch.outputs.branch }} - # Edit config.json and .gitmodules so there is a single submodule - # pointing to the version of the docs to deploy to the preview site. - run: | - git rm content/* - git submodule add --force -b "${BRANCH}" https://github.com/gravitational/teleport content/preview - echo "{\"versions\": [{\"name\": \"preview\", \"branch\": \"preview\", \"deprecated\": false, \"latest\": true}]}" > config.json - git submodule update --init --remote --progress - - name: Install Vercel CLI - run: yarn global add vercel@latest - - name: Pull Vercel Environment Information - run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }} - - name: Build Project Artifacts - run: vercel build --token=${{ secrets.VERCEL_TOKEN }} - - name: Deploy Project Artifacts to Vercel - id: deploy - run: | - vercel deploy --archive=tgz --prebuilt --token=${{ secrets.VERCEL_TOKEN }} > deployment-url.txt - preview_url="$(cat deployment-url.txt)" - echo "PREVIEW_URL=$preview_url" >> $GITHUB_OUTPUT - - uses: actions/github-script@v7 - env: - PREVIEW_URL: ${{ steps.deploy.outputs.PREVIEW_URL }} - with: - script: | - const previewUrl = process.env.PREVIEW_URL - - github.rest.issues.createComment({ - issue_number: context.issue.number, - owner: context.repo.owner, - repo: context.repo.repo, - body: `🤖 Vercel preview here: ${previewUrl}/docs` - }) diff --git a/docs/cspell.json b/docs/cspell.json index 9c8b9d51e36b6..12c33f497afc7 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -2,6 +2,14 @@ "language": "en", "version": "0.2", "words": [ + "aada", + "abee", + "fffc", + "fabfc", + "microservices", + "configmaps", + "genrsa", + "displayname", "AADUSER", "ABCDEFGHIJKL", "ADFS", diff --git a/docs/pages/enroll-resources/application-access/guides/connecting-apps.mdx b/docs/pages/enroll-resources/application-access/guides/connecting-apps.mdx index 26ed6d6c3fbc9..816ae2484d96c 100644 --- a/docs/pages/enroll-resources/application-access/guides/connecting-apps.mdx +++ b/docs/pages/enroll-resources/application-access/guides/connecting-apps.mdx @@ -132,10 +132,9 @@ Teleport, you must configure these yourself: Service domain, e.g., `*.teleport.example.com`, with the domain name of the Teleport Proxy Service. -1. Ensure that your system provisionings TLS certificates for - Teleport-registered applications. The method to use depends on how you - originally set up TLS for your self-hosted Teleport deployment, and is - outside the scope of this guide. +1. Ensure that your system provisions TLS certificates for Teleport-registered + applications. The method to use depends on how you originally set up TLS for + your self-hosted Teleport deployment, and is outside the scope of this guide. In general, the same system that provisions TLS certificates signed for the web address of the Proxy Service (e.g., `teleport.example.com`) must also diff --git a/docs/pages/reference/resources.mdx b/docs/pages/reference/resources.mdx index 7705f6456d4c9..55bc6c6e5e117 100644 --- a/docs/pages/reference/resources.mdx +++ b/docs/pages/reference/resources.mdx @@ -126,7 +126,7 @@ When no `kubernetes_resource` is set: {/* This table is cursed. Our current docs engine doesn't support HTML tables (due to SSR and the rehydration process). We have dto do everything inlined in markdown. Some HTML character codes are used to render specific chars like {} -or to avoid line breaks in the middle fo the YAML. Whitespaces before br tags +or to avoid line breaks in the middle fo the YAML. Spaces before br tags are required.*/} | Allow rule | Role v5 | Role v6 | Role v7 | diff --git a/docs/pages/reference/signature-algorithms.mdx b/docs/pages/reference/signature-algorithms.mdx index 8b96acfe67be5..c41186f3d7bc3 100644 --- a/docs/pages/reference/signature-algorithms.mdx +++ b/docs/pages/reference/signature-algorithms.mdx @@ -192,8 +192,8 @@ in each suite. Try it and let us know! We aim to balance security, performance, and compatibility with the chosen signature algorithm suites. -It is okay to continue using the `legacy` suite for the forseeable future and we -expect it may be required for some user's environments. +It is okay to continue using the `legacy` suite for the foreseeable future and we +expect it may be required for some users' environments. ### How did you choose these algorithms?