Skip to content

Commit ca2aabb

Browse files
ptgottptgott
committed
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
1 parent e2ee237 commit ca2aabb

File tree

5 files changed

+60
-84
lines changed

5 files changed

+60
-84
lines changed

‎.github/workflows/doc-tests.yaml

Lines changed: 48 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -44,23 +44,54 @@ jobs:
4444
- name: Checkout
4545
uses: actions/checkout@v4
4646
with:
47-
repository: "gravitational/docs"
48-
path: "docs"
47+
repository: 'gravitational/teleport'
48+
path: 'teleport'
49+
50+
- name: Checkout
51+
uses: actions/checkout@v4
52+
with:
53+
repository: 'gravitational/docs-website'
54+
path: 'docs'
55+
56+
# Cache node_modules. Unlike the example in the actions/cache repo, this
57+
# caches the node_modules directory instead of the yarn cache. This is
58+
# because yarn needs to build fresh packages even when it copies files
59+
# from the yarn cache into node_modules.
60+
# See:
61+
# https://github.com/actions/cache/blob/main/examples.md#node---yarn
62+
- uses: actions/cache@v4
63+
id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
64+
with:
65+
path: '${{ github.workspace }}/docs/node_modules'
66+
key: ${{ runner.os }}-yarn-${{ hashFiles(format('{0}/docs/yarn.lock', github.workspace)) }}
67+
restore-keys: |
68+
${{ runner.os }}-yarn-
69+
70+
- name: Install docs site dependencies
71+
working-directory: docs
72+
if: ${{ steps.yarn-cache.outputs.cache-hit != 'true' }}
73+
# Prevent occasional `yarn install` executions that run indefinitely
74+
timeout-minutes: 10
75+
run: yarn install
4976

5077
- name: Prepare docs site configuration
5178
# The environment we use for linting the docs differs from the one we
5279
# use for the live docs site in that we only test a single version of
5380
# the content.
5481
#
55-
# To do this, we replace the three submodules we use for building the
56-
# live docs site with a single submodule, pointing to the
57-
# gravitational/teleport branch we are linting.
58-
#
82+
# To do this, we delete the three submodules we use for building the
83+
# live docs site and copy a gravitational/teleport clone into the
84+
# content directory.
85+
#
5986
# The docs engine expects a config.json file at the root of the
6087
# gravitational/docs clone that associates directories with git
6188
# submodules. By default, these directories represent versioned branches
6289
# of gravitational/teleport. We override this in order to build only a
6390
# single version of the docs.
91+
#
92+
# We also replace data fetched from Sanity CMS with hardcoded JSON
93+
# objects to remove the need to authenticate with Sanity. Each includes
94+
# the minimal set of data required for docs builds to succeed.
6495
run: |
6596
if [ $GITHUB_EVENT_NAME = "pull_request" ]; then
6697
BRANCH=$GITHUB_HEAD_REF;
@@ -78,16 +109,19 @@ jobs:
78109
cd $GITHUB_WORKSPACE/docs
79110
echo "" > .gitmodules
80111
rm -rf content/*
81-
cd content
82-
# Add a submodule at docs/content/teleport
83-
git submodule add --force -b $BRANCH -- https://github.com/gravitational/teleport
84-
cd $GITHUB_WORKSPACE/docs
85-
echo "{\"versions\": [{\"name\": \"teleport\", \"branch\": \"$BRANCH\", \"deprecated\": false}]}" > $GITHUB_WORKSPACE/docs/config.json
86-
yarn install
87-
yarn build-node
112+
# Rather than using a submodule, copy the teleport source into the
113+
# content directory.
114+
cp -r "$GITHUB_WORKSPACE/teleport" "$GITHUB_WORKSPACE/docs/content/current"
115+
jq -nr --arg version "current" '{"versions": [{"name": $version,"branch": $version,"deprecated": false,"isDefault": true}]}' > config.json
116+
NEW_PACKAGE_JSON=$(jq '.scripts."git-update" = "echo Skipping submodule update"' package.json);
117+
NEW_PACKAGE_JSON=$(jq '.scripts."prepare-sanity-data" = "echo Using pre-populated Sanity data"' <<< "$NEW_PACKAGE_JSON");
118+
echo "$NEW_PACKAGE_JSON" > package.json;
119+
echo "{}" > data/events.json
120+
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
88121
89122
- name: Check spelling
90-
run: cd $GITHUB_WORKSPACE/docs && yarn spellcheck content/teleport
123+
working-directory: 'docs'
124+
run: yarn spellcheck content/current
91125

92126
- name: Lint the docs
93127
run: cd $GITHUB_WORKSPACE/docs && yarn markdown-lint

‎.github/workflows/vercel-preview.yaml

Lines changed: 0 additions & 65 deletions
This file was deleted.

‎docs/cspell.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,14 @@
22
"language": "en",
33
"version": "0.2",
44
"words": [
5+
"aada",
6+
"abee",
7+
"fffc",
8+
"fabfc",
9+
"microservices",
10+
"configmaps",
11+
"genrsa",
12+
"displayname",
513
"AADUSER",
614
"ABCDEFGHIJKL",
715
"ADFS",

‎docs/pages/enroll-resources/application-access/guides/connecting-apps.mdx

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -132,10 +132,9 @@ Teleport, you must configure these yourself:
132132
Service domain, e.g., `*.teleport.example.com`, with the domain name of the
133133
Teleport Proxy Service.
134134

135-
1. Ensure that your system provisionings TLS certificates for
136-
Teleport-registered applications. The method to use depends on how you
137-
originally set up TLS for your self-hosted Teleport deployment, and is
138-
outside the scope of this guide.
135+
1. Ensure that your system provisions TLS certificates for Teleport-registered
136+
applications. The method to use depends on how you originally set up TLS for
137+
your self-hosted Teleport deployment, and is outside the scope of this guide.
139138

140139
In general, the same system that provisions TLS certificates signed for the
141140
web address of the Proxy Service (e.g., `teleport.example.com`) must also

‎docs/pages/reference/resources.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@ When no `kubernetes_resource` is set:
126126
{/* This table is cursed. Our current docs engine doesn't support HTML tables
127127
(due to SSR and the rehydration process). We have dto do everything inlined in
128128
markdown. Some HTML character codes are used to render specific chars like {}
129-
or to avoid line breaks in the middle fo the YAML. Whitespaces before br tags
129+
or to avoid line breaks in the middle fo the YAML. Spaces before br tags
130130
are required.*/}
131131

132132
| Allow rule | Role v5 | Role v6 | Role v7 |

0 commit comments

Comments
 (0)