Skip to content

Commit 0e58fc4

Browse files
kbatuigasJakeSCahill
kbatuigas
and
JakeSCahill
authored
Feedback links (#16)
* Fix link * Use overlays to add feedback links to docs * Use correct GitHub URL * Allow for shared self-managed overlays * Check for non-existent files * Check for non-existent files * Test diff * Test overlays * Test diff * Test diff * Add feedbacklink * Replace swagger with openapi * Update http-proxy.json * Update schema-registry.json * Update cloud-controlplane.yaml * Update admin.yaml * Update feedback link text --------- Co-authored-by: JakeSCahill <[email protected]> Co-authored-by: Jake Cahill <[email protected]>
1 parent f1ddc7f commit 0e58fc4

File tree

11 files changed

+82
-75
lines changed

11 files changed

+82
-75
lines changed

‎.github/workflows/bump.yml

Lines changed: 45 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -24,57 +24,26 @@ jobs:
2424
with:
2525
fetch-depth: 0
2626

27-
- name: Get changed files
28-
id: changed-files
29-
run: |
30-
if [[ "${{ github.event_name }}" == "pull_request" ]]; then
31-
CHANGED_FILES=$(git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.head.sha }})
32-
else
33-
CHANGED_FILES=$(git diff --name-only ${{ github.event.before }} ${{ github.event.after }})
34-
fi
35-
echo "CHANGED_FILES<<EOF" >> $GITHUB_ENV
36-
echo "$CHANGED_FILES" >> $GITHUB_ENV
37-
echo "EOF" >> $GITHUB_ENV
38-
3927
- name: Set matrix
4028
id: set-matrix
4129
run: |
4230
DOCS=()
43-
44-
# Check for changes in API doc folders
45-
if echo "$CHANGED_FILES" | grep -q "^admin/"; then
46-
DOCS+=("admin")
47-
fi
48-
if echo "$CHANGED_FILES" | grep -q "^cloud-controlplane/"; then
49-
DOCS+=("cloud-controlplane")
50-
fi
51-
if echo "$CHANGED_FILES" | grep -q "^cloud-dataplane/"; then
52-
DOCS+=("cloud-dataplane")
53-
fi
54-
if echo "$CHANGED_FILES" | grep -q "^schema-registry/"; then
55-
DOCS+=("schema-registry")
56-
fi
57-
if echo "$CHANGED_FILES" | grep -q "^http-proxy/"; then
58-
DOCS+=("http-proxy")
59-
fi
60-
# Check for changes in shared resources that might affect all docs
61-
if echo "$CHANGED_FILES" | grep -q "^shared/"; then
62-
if [ ${#DOCS[@]} -eq 0 ]; then
63-
# If only shared files changed and no specific doc files, include all docs
64-
DOCS+=("admin" "cloud-controlplane" "cloud-dataplane" "schema-registry" "http-proxy")
31+
for d in */ ; do
32+
# Exclude shared and .github or any other non-doc folders
33+
if [[ "$d" != "shared/" && "$d" != ".github/" && ( -f "${d%/}/${d%/}.yaml" || -f "${d%/}/${d%/}.json" ) ]]; then
34+
DOCS+=("${d%/}")
6535
fi
66-
fi
36+
done
6737
68-
# If no files changed in any monitored directories, abort the workflow
38+
# If no doc folders found, abort the workflow
6939
if [ ${#DOCS[@]} -eq 0 ]; then
70-
echo "No relevant files were changed. Exiting workflow."
40+
echo "No doc folders found. Exiting workflow."
7141
echo "matrix={\"doc_id\":[]}" >> $GITHUB_OUTPUT
7242
exit 0
7343
fi
7444
75-
# Convert bash array to JSON array for GitHub Actions matrix
7645
JSON_ARRAY=$(printf '"%s",' "${DOCS[@]}" | sed 's/,$//')
77-
JSON_MATRIX="{\"doc_id\":[$JSON_ARRAY]}"
46+
JSON_MATRIX="{\"doc_id\":[${JSON_ARRAY}]}"
7847
echo "matrix=$JSON_MATRIX" >> $GITHUB_OUTPUT
7948
echo "Created matrix: $JSON_MATRIX"
8049
@@ -107,35 +76,39 @@ jobs:
10776
run: |
10877
OVERLAYS=""
10978
110-
# Check for doc-specific overlays
79+
# Add doc-specific overlays (if any)
11180
if [ -d "${{ matrix.doc_id }}/overlays" ]; then
81+
shopt -s nullglob
11282
for overlay_file in "${{ matrix.doc_id }}/overlays"/*.yaml; do
11383
if [ -f "$overlay_file" ]; then
114-
if [ -n "$OVERLAYS" ]; then
115-
OVERLAYS="$OVERLAYS,$overlay_file"
116-
else
117-
OVERLAYS="$overlay_file"
118-
fi
84+
OVERLAYS="${OVERLAYS:+$OVERLAYS,}$overlay_file"
11985
fi
12086
done
87+
shopt -u nullglob
12188
fi
12289
123-
# Check for shared overlays - only apply to cloud APIs
124-
if [[ "${{ matrix.doc_id }}" == "cloud-"* ]] && [ -d "shared/overlays" ]; then
125-
for overlay_file in shared/overlays/*.yaml; do
90+
# Determine shared overlay prefix
91+
if [[ "${{ matrix.doc_id }}" == "cloud-"* ]]; then
92+
OVERLAY_PREFIX="cloud-"
93+
else
94+
OVERLAY_PREFIX="sm-"
95+
fi
96+
97+
# Add matching shared overlays
98+
if [ -d "shared/overlays" ]; then
99+
shopt -s nullglob
100+
for overlay_file in shared/overlays/${OVERLAY_PREFIX}*.yaml; do
126101
if [ -f "$overlay_file" ]; then
127-
if [ -n "$OVERLAYS" ]; then
128-
OVERLAYS="$OVERLAYS,$overlay_file"
129-
else
130-
OVERLAYS="$overlay_file"
131-
fi
102+
OVERLAYS="${OVERLAYS:+$OVERLAYS,}$overlay_file"
132103
fi
133104
done
105+
shopt -u nullglob
134106
fi
135107
136108
echo "overlay_paths=$OVERLAYS" >> $GITHUB_OUTPUT
137109
echo "Using overlays: $OVERLAYS"
138110
111+
139112
- name: Deploy API documentation
140113
uses: bump-sh/github-action@v1
141114
with:
@@ -150,7 +123,7 @@ jobs:
150123
api-diff:
151124
if: ${{ github.event_name == 'pull_request' && fromJson(needs.determine-doc-ids.outputs.matrix).doc_id[0] != null }}
152125
needs: determine-doc-ids
153-
name: Check API diff on Bump.sh
126+
name: Check diff
154127
runs-on: ubuntu-latest
155128
strategy:
156129
matrix: ${{fromJson(needs.determine-doc-ids.outputs.matrix)}}
@@ -178,35 +151,39 @@ jobs:
178151
run: |
179152
OVERLAYS=""
180153
181-
# Check for doc-specific overlays
154+
# Add doc-specific overlays (if any)
182155
if [ -d "${{ matrix.doc_id }}/overlays" ]; then
156+
shopt -s nullglob
183157
for overlay_file in "${{ matrix.doc_id }}/overlays"/*.yaml; do
184158
if [ -f "$overlay_file" ]; then
185-
if [ -n "$OVERLAYS" ]; then
186-
OVERLAYS="$OVERLAYS,$overlay_file"
187-
else
188-
OVERLAYS="$overlay_file"
189-
fi
159+
OVERLAYS="${OVERLAYS:+$OVERLAYS,}$overlay_file"
190160
fi
191161
done
162+
shopt -u nullglob
192163
fi
193164
194-
# Check for shared overlays - only apply to cloud APIs
195-
if [[ "${{ matrix.doc_id }}" == "cloud-"* ]] && [ -d "shared/overlays" ]; then
196-
for overlay_file in shared/overlays/*.yaml; do
165+
# Determine shared overlay prefix
166+
if [[ "${{ matrix.doc_id }}" == "cloud-"* ]]; then
167+
OVERLAY_PREFIX="cloud-"
168+
else
169+
OVERLAY_PREFIX="sm-"
170+
fi
171+
172+
# Add matching shared overlays
173+
if [ -d "shared/overlays" ]; then
174+
shopt -s nullglob
175+
for overlay_file in shared/overlays/${OVERLAY_PREFIX}*.yaml; do
197176
if [ -f "$overlay_file" ]; then
198-
if [ -n "$OVERLAYS" ]; then
199-
OVERLAYS="$OVERLAYS,$overlay_file"
200-
else
201-
OVERLAYS="$overlay_file"
202-
fi
177+
OVERLAYS="${OVERLAYS:+$OVERLAYS,}$overlay_file"
203178
fi
204179
done
180+
shopt -u nullglob
205181
fi
206182
207183
echo "overlay_paths=$OVERLAYS" >> $GITHUB_OUTPUT
208184
echo "Using overlays: $OVERLAYS"
209185
186+
210187
- name: Comment pull request with API diff
211188
uses: bump-sh/github-action@v1
212189
with:

‎admin/admin.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6059,4 +6059,4 @@ tags:
60596059
- name: Services
60606060
description: Manage Redpanda services.
60616061
- name: Unstable APIs
6062-
description: Developmental APIs that are subject to change.
6062+
description: Developmental APIs that are subject to change.

‎cloud-controlplane/overlays/add-x-topics.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ actions:
1717
$ref: ../../shared/x-topics/cloud-api-overview.md
1818
- title: Authentication
1919
content:
20-
$ref: ../../shared/x-topics/about-authentication.md
20+
$ref: ../../shared/x-topics/cloud-about-authentication.md
2121
- title: Regions and Usage Tiers
2222
content:
2323
$ref: ../x-topics/cloud-regions.md

‎cloud-controlplane/x-topics/quickstart.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,10 +91,10 @@ If you successfully retrieve an access token, it is valid for one hour. You can
9191
1. Select an operation, for example **Create topic** or **List users**.
9292
1. In the URL field, add the data plane API URL. You can now make Data Plane API requests to your target cluster.
9393

94-
See also: [Data Plane API Quickstart](/cloud-dataplane/topic/topic-quickstart)
94+
See also: [Data Plane API Quickstart](/api/doc/cloud-dataplane/topic/topic-quickstart)
9595

9696
## Suggested reading
9797

9898
- Learn about Redpanda Cloud [network security and connectivity](https://docs.redpanda.com/redpanda-cloud/networking/) for BYOC and Dedicated clusters.
9999
- Manage [authentication and authorization](https://docs.redpanda.com/redpanda-cloud/security/authorization/) in Redpanda Cloud.
100-
- [Create a Kafka client or generate a sample application](https://docs.redpanda.com/redpanda-cloud/get-started/cluster-types/serverless/#connect-with-your-cluster) to interact with your Serverless cluster.
100+
- [Create a Kafka client or generate a sample application](https://docs.redpanda.com/redpanda-cloud/get-started/cluster-types/serverless/#connect-with-your-cluster) to interact with your Serverless cluster.

‎cloud-dataplane/overlays/add-x-topics.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ actions:
1717
$ref: ../../shared/x-topics/cloud-api-overview.md
1818
- title: Authentication
1919
content:
20-
$ref: ../../shared/x-topics/about-authentication.md
20+
$ref: ../../shared/x-topics/cloud-about-authentication.md
2121
- title: Error and Status Codes
2222
content:
2323
$ref: ../x-topics/error-and-status-codes.md

‎http-proxy/http-proxy.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -570,4 +570,4 @@
570570
}
571571
}
572572
}
573-
}
573+
}

‎schema-registry/schema-registry.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1661,4 +1661,4 @@
16611661
}
16621662
}
16631663
}
1664-
}
1664+
}

‎shared/overlays/cloud-add-feedback-link.yaml

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Overlay to add feedback link to the API specification
2+
# This adds a feedback button in the Control Plane and Data Plane API docs
3+
# for users to report issues through GitHub
4+
5+
overlay: 1.0.0
6+
info:
7+
title: Add Feedback Link
8+
version: 1.0.0
9+
actions:
10+
# Add x-feedbackLink to the top-level info element
11+
- target: "$.info"
12+
update:
13+
x-feedbackLink:
14+
label: "Share feedback"
15+
url: "https://github.com/redpanda-data/cloud-docs/issues/new?template=01_doc_request.yml"

‎shared/overlays/update-securityschemes-for-authentication.yaml renamed to ‎shared/overlays/cloud-update-securityschemes-for-authentication.yaml

File renamed without changes.

‎shared/overlays/sm-add-feedback-link.yaml

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Overlay to add feedback link to the API specification
2+
# This adds a feedback button in the HTTP Proxy, Schema Registry, and Admin API docs
3+
# for users to report issues through GitHub
4+
5+
overlay: 1.0.0
6+
info:
7+
title: Add Feedback Link
8+
version: 1.0.0
9+
actions:
10+
# Add x-feedbackLink to the top-level info element
11+
- target: "$.info"
12+
update:
13+
x-feedbackLink:
14+
label: "Share feedback"
15+
url: "https://github.com/redpanda-data/docs/issues/new?template=01_doc_request.yml"

0 commit comments

Comments
 (0)