Skip to content

Commit 6a2eeab

Browse files
author
Paul Fitzgerald
committed
feat(RELEASE-1675): auto generate README.md files for tasks/pipelines
Add readme_generator.sh, which generates README.md files for tasks and pipelines, as well as a check_readme.sh script and workflow to check that the README.md files in each task and pipeline match the output of readme-generator.sh. Also updated CONTRIBUTING.md to mention this new requirement. Add check_param_punctuation.sh and workflow to stop '.' from being added to the end of task/pipeline param descriptions. Signed-off-by: Paul Fitzgerald <pafitzge@redhat.com>
1 parent f7724b5 commit 6a2eeab

5 files changed

Lines changed: 483 additions & 0 deletions

File tree

‎.github/scripts/check_param_punctuation.sh‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
#!/usr/bin/env bash
2+
3+
# This script will verify that the '.spec.param.description' of all task and
4+
# pipeline directories provided matches the output of hack/readme_generator.sh
5+
# does not end with an invalid character.
6+
#
7+
# Task and pipeline directories are provided
8+
# either via PARAM_ITEMS env var, or as arguments
9+
# when running the script.
10+
11+
CLI_PARAM_ITEMS=()
12+
13+
show_help() {
14+
echo "Usage: $0 [item1] [item2] [...]"
15+
echo
16+
echo Flags:
17+
echo " --help: Show this help message"
18+
echo
19+
echo "Items are task or pipeline directories. They can be supplied"
20+
echo "either as arguments or via the PARAM_ITEMS environment variable."
21+
echo
22+
echo "Examples:"
23+
echo " $0 tasks/managed/apply-mapping"
24+
echo
25+
echo " or"
26+
echo
27+
echo ' export PARAM_ITEMS="mydir/tasks/apply-mapping some/other/dir"'
28+
echo " $0"
29+
exit 1
30+
}
31+
32+
while [[ $# -gt 0 ]]; do
33+
case "$1" in
34+
--help)
35+
show_help
36+
;;
37+
--*)
38+
show_help
39+
;;
40+
*)
41+
CLI_PARAM_ITEMS+=("$1")
42+
shift
43+
;;
44+
esac
45+
done
46+
47+
if [[ "${#CLI_PARAM_ITEMS[@]}" -gt 0 ]]; then
48+
PARAM_ITEMS=("${CLI_PARAM_ITEMS[@]}")
49+
else
50+
read -r -a PARAM_ITEMS <<< "$PARAM_ITEMS"
51+
fi
52+
53+
if [ "${#PARAM_ITEMS[@]}" -eq 0 ]
54+
then
55+
show_help
56+
fi
57+
58+
# Check that all directories exist. If not, fail
59+
for ITEM in "${PARAM_ITEMS[@]}"
60+
do
61+
if [[ -d "$ITEM" ]]; then
62+
true
63+
else
64+
echo "Error: Invalid file or directory: $ITEM"
65+
exit 1
66+
fi
67+
done
68+
69+
for ITEM in "${PARAM_ITEMS[@]}"
70+
do
71+
echo "Task/Pipeline item: $ITEM"
72+
ITEM_NAME=$(basename "$ITEM")
73+
ITEM_DIR=$(echo "$ITEM" | cut -d '/' -f -3)
74+
echo " Task/Pipeline name: $ITEM_NAME"
75+
76+
ITEM_PATH=${ITEM_DIR}/${ITEM_NAME}.yaml
77+
PARAMS=$(yq .spec.params "$ITEM_PATH")
78+
79+
for ((i=0; i < $(yq length <<< "$PARAMS"); i++)); do
80+
# Get rid of newlines and remove trailing whitespace
81+
DESCRIPTION="$(yq .[$i].description <<< "$PARAMS" | tr '\n' ' ' | sed 's/[[:space:]]*$//')"
82+
if [[ "${DESCRIPTION: -1}" =~ [.,] ]]; then
83+
NAME="$(yq .[$i].name <<< "$PARAMS" | tr '\n' ' ' | sed 's/[[:space:]]*$//')"
84+
echo " Error in $NAME: Description should not end with a '${DESCRIPTION: -1}'"
85+
FAILED_PARAMS+=("$ITEM_PATH: $NAME")
86+
fi
87+
done
88+
done
89+
90+
if [[ "${#FAILED_PARAMS[@]}" -eq 0 ]]; then
91+
echo
92+
echo "All task/pipeline parameter descriptions are valid."
93+
else
94+
echo
95+
echo "Error: these task/pipeline parameter descriptions must be updated:"
96+
for PARAM in "${FAILED_PARAMS[@]}"; do
97+
echo " $PARAM"
98+
done
99+
exit 1
100+
fi

‎.github/scripts/check_readme.sh‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
#!/bin/bash
2+
3+
# This script will verify that the README.md of all task and
4+
# pipeline directories provided matches the output of hack/readme_generator.sh
5+
# to ensure that README files are up to date.
6+
#
7+
# Task and pipeline directories are provided
8+
# either via README_ITEMS env var, or as arguments
9+
# when running the script.
10+
11+
# yield empty strings for unmatched patterns
12+
shopt -s nullglob
13+
14+
CLI_README_ITEMS=()
15+
16+
show_help() {
17+
echo "Usage: $0 [item1] [item2] [...]"
18+
echo
19+
echo Flags:
20+
echo " --help: Show this help message"
21+
echo
22+
echo "Items are task or pipeline directories. They can be supplied"
23+
echo "either as arguments or via the README_ITEMS environment variable."
24+
echo
25+
echo "Examples:"
26+
echo " $0 tasks/managed/apply-mapping"
27+
echo
28+
echo " or"
29+
echo
30+
echo ' export README_ITEMS="mydir/tasks/apply-mapping some/other/dir"'
31+
echo " $0"
32+
exit 1
33+
}
34+
35+
while [[ $# -gt 0 ]]; do
36+
case "$1" in
37+
--help)
38+
show_help
39+
;;
40+
--*)
41+
show_help
42+
;;
43+
*)
44+
CLI_README_ITEMS+=("$1")
45+
shift
46+
;;
47+
esac
48+
done
49+
50+
if [[ "${#CLI_README_ITEMS[@]}" -gt 0 ]]; then
51+
README_ITEMS=("${CLI_README_ITEMS[@]}")
52+
else
53+
read -r -a README_ITEMS <<< "$README_ITEMS"
54+
fi
55+
56+
if [ "${#README_ITEMS[@]}" -eq 0 ]
57+
then
58+
show_help
59+
fi
60+
61+
# Check that all directories exist. If not, fail
62+
for ITEM in "${README_ITEMS[@]}"
63+
do
64+
if [[ -d "$ITEM" ]]; then
65+
true
66+
else
67+
echo "Error: Invalid file or directory: $ITEM"
68+
exit 1
69+
fi
70+
done
71+
72+
for ITEM in "${README_ITEMS[@]}"
73+
do
74+
echo "Task/Pipeline item: $ITEM"
75+
ITEM_NAME=$(basename "$ITEM")
76+
ITEM_DIR=$(echo "$ITEM" | cut -d '/' -f -3)
77+
echo " Task/Pipeline name: $ITEM_NAME"
78+
79+
ITEM_PATH=${ITEM_DIR}/${ITEM_NAME}.yaml
80+
if [ ! -f "$ITEM_PATH" ]
81+
then
82+
echo "Error: Task/Pipeline file does not exist: $ITEM_PATH"
83+
exit 1
84+
fi
85+
86+
README_PATH=${ITEM_DIR}/README.md
87+
if [ ! -f "$README_PATH" ]
88+
then
89+
echo "Error: README does not exist in $ITEM_DIR"
90+
exit 1
91+
fi
92+
93+
if ! diff -u <(hack/readme_generator.sh --dry-run "$ITEM_DIR") "$README_PATH"; then
94+
echo " Error: README.md has not been updated. Please use hack/readme-generator.sh to" \
95+
"generate a new README.md to replace $ITEM/README.md"
96+
FAILED_ITEMS+=("$ITEM")
97+
else
98+
echo " README.md for $ITEM_DIR is up to date"
99+
fi
100+
101+
done
102+
103+
if [[ "${#FAILED_ITEMS[@]}" -eq 0 ]]; then
104+
echo
105+
echo "All README.md files are up to date"
106+
else
107+
echo
108+
echo "Error: these task/pipeline README.md files must be updated:"
109+
for ITEM in "${FAILED_ITEMS[@]}"; do
110+
echo " $ITEM"
111+
done
112+
echo
113+
echo "Try running the following command to fix this:"
114+
echo "./hack/readme_generator.sh ${FAILED_ITEMS[@]}"
115+
exit 1
116+
fi

‎.github/workflows/lint.yaml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,3 +109,49 @@ jobs:
109109
run: .github/scripts/tkn_check_compute_resources.sh
110110
env:
111111
CHANGED_FILES: ${{ steps.changed-files.outputs.all_changed_files }}
112+
check-readme:
113+
name: Check README.md files
114+
runs-on: ubuntu-latest
115+
steps:
116+
- name: Checkout code
117+
uses: actions/checkout@v4
118+
- name: Get changed dirs
119+
id: changed-dirs
120+
uses: tj-actions/changed-files@ed68ef82c095e0d48ec87eccea555d944a631a4c # v45.0.6
121+
with:
122+
files: |
123+
tasks/*/**
124+
pipelines/*/**
125+
dir_names: "true"
126+
dir_names_max_depth: "3"
127+
- name: Check README.md files
128+
if: |
129+
steps.changed-dirs.outputs.any_changed == 'true'
130+
run: .github/scripts/check_readme.sh
131+
env:
132+
README_ITEMS: >-
133+
${{ steps.changed-dirs.outputs.all_changed_files }}
134+
check-param-punctuation:
135+
name: Check param punctuation
136+
runs-on: ubuntu-latest
137+
steps:
138+
- name: Checkout code
139+
uses: actions/checkout@v4
140+
- name: Get changed dirs
141+
id: changed-dirs
142+
uses: tj-actions/changed-files@ed68ef82c095e0d48ec87eccea555d944a631a4c # v45.0.6
143+
with:
144+
files: |
145+
tasks/*/**
146+
pipelines/*/**
147+
files_ignore: |
148+
**/*.md
149+
dir_names: "true"
150+
dir_names_max_depth: "3"
151+
- name: Check README.md files
152+
if: |
153+
steps.changed-dirs.outputs.any_changed == 'true'
154+
run: .github/scripts/check_param_punctuation.sh
155+
env:
156+
PARAM_ITEMS: >-
157+
${{ steps.changed-dirs.outputs.all_changed_files }}

‎CONTRIBUTING.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,15 @@ Here is an example
125125
cpu: 250m
126126
```
127127
128+
### Keeping Documentation Up to Date
129+
130+
Whenever a task or pipeline is changed, please run the `./hack/readme_generator.sh` script with the
131+
changed task/pipeline directories as arguments to update the README.md description and table included with the
132+
table.
133+
134+
A check defined in `.github/scripts/check_readme.sh` is run on each pull request to ensure that the README.md files in each task/pipeline are up to date.
135+
For more information, check the `./hack/readme_generator.sh` and `./github/scripts/check_readme.sh` scripts.
136+
128137
### Modes for Running Pipelines
129138

130139
Note: There are currently 2 modes that may be used when running pipelines:

0 commit comments

Comments
 (0)