Skip to content

Commit 6374e6f

Browse files
jkowalleckjkowalleck
authored
Docs/docsgen one version only (#587)
Allow the docs generators to run for a certain version. Previously, they always ran for all in series. --- > original from #507 from @Nicolas-Peiffer The JSON Schema HTML viewer generator script `docgen/json/gen.sh` supports generating only for one particular CycloneDX version, including the possibility of generating the HTML only for draft version of CycloneDX during dev time. ## Use Case I want to propose new objects in the CycloneDX Specification. And for checking the JSON Schema, I like to locally use the HTML view to check the content of the JSON Schema. However, during dev time when I was modifying the JSON Schema, I found it not convenient that the script `docgen/json/gen.sh` regenerate the HTML doc for every version of CycloneDX each time I run it when I only need the version I am working on. ## Proposition I modified the script `docgen/json/gen.sh` to be able to run `gen.sh` only for a particular version of CycloneDX. For example: ```bash ./gen.sh 1.6 ``` But I also added a list `DRAFT_CYCLONEDX_VERSIONS` for when I am working on a draft proposition of CycloneDX spec. For example: ```bash # I modify `docgen/json/gen.sh` to add the name of my draft file DRAFT_CYCLONEDX_VERSIONS=(my_cdx_dev_draft) ``` I create a JSON schema draft file `schema/bom-my_cdx_dev_draft.schema.json`: Then I run: ```bash ./gen.sh my_cdx_dev_draft ``` Which creates only the HTML for `my_cdx_dev_draft` ```bash tree docgen/json/docs/my_cdx_dev_draft/ docgen/json/docs/my_cdx_dev_draft/ ├── index.html ├── schema_doc.css └── schema_doc.min.j ``` And in order not to disturb the way `docgen/json/gen.sh` works now, running it without argument generates the HTML for all the CDX versions: ```bash ./gen.sh ``` ```bash ls -1 docgen/json/docs/ 1.2 1.3 1.4 1.5 1.6 ``` I also added a small usage help message. ```bash ./gen.sh -h Deleting folder /home/thedetective/Documents/dev-workspace/cyclonedx/cyclonedx-specification.thalesgroup/docgen/json/docs Usage: Generate HTML JSON Schema navigator for CyccloneDX Usage: ./gen.sh <version> : runs only for <version> ./gen.sh : loops over all valid and draft CycloneDX versions ``` ## What about `docgen/xml/gen.sh` ? I will probably propose the same kind of modification to the XML `docgen/xml/gen.sh` script to achieve the same results. ## Conclusion There are probably other way to achieve this result. I think this one is the cheapest in terms of how the `gen.sh` script is modified. ---- supersedes #507 closes #507
2 parents ca1a2fd + 49077b0 commit 6374e6f

File tree

3 files changed

+219
-49
lines changed

3 files changed

+219
-49
lines changed

‎docgen/json/gen.sh‎

Lines changed: 77 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,60 @@
11
#!/bin/bash
22
set -eu
33

4+
declare -a CDX_VERSIONS=(
5+
'1.6'
6+
'1.5'
7+
'1.4'
8+
'1.3'
9+
'1.2'
10+
)
11+
12+
# region help
13+
DESC="Generate HTML Schema navigator for CycloneDX JSON"
14+
USAGE="
15+
Usage: $0 [CDX_VERSION...]
16+
17+
Supported values for CDX_VERSION: ${CDX_VERSIONS[*]}
18+
"
19+
# endregion help
20+
21+
422
THIS_PATH="$(realpath "$(dirname "$0")")"
523
SCHEMA_PATH="$(realpath "$THIS_PATH/../../schema")"
624
DOCS_PATH="$THIS_PATH/docs"
725
TEMPLATES_PATH="$THIS_PATH/templates"
826

9-
rm -f -R "$DOCS_PATH"
1027

11-
# Check to see if generate-schema-doc is executable and is in the path. If not, install JSON Schema for Humans.
12-
if ! [ -x "$(command -v generate-schema-doc)" ]
13-
then
14-
# dependencies managed externally, so dependebot/renovate can pick it up
15-
pip3 install -r "$THIS_PATH/requirements.txt"
16-
fi
28+
# --
29+
30+
prepare () {
31+
# Check to see if generate-schema-doc is executable and is in the path.
32+
# If not, install JSON Schema for Humans.
33+
if ! [ -x "$(command -v generate-schema-doc)" ]
34+
then
35+
# dependencies managed externally, so dependebot/renovate can pick it up
36+
python -m pip install -r "$THIS_PATH/requirements.txt"
37+
fi
38+
}
39+
1740

1841
generate () {
19-
version="$1"
20-
title="CycloneDX v${version} JSON Reference"
42+
local version="$1"
43+
local title="CycloneDX v${version} JSON Reference"
2144
echo "Generating: $title"
2245

23-
SCHEMA_FILE="$SCHEMA_PATH/bom-${version}.schema.json"
24-
STRICT_SCHEMA_FILE="$SCHEMA_PATH/bom-${version}-strict.schema.json"
46+
local SCHEMA_FILE="$SCHEMA_PATH/bom-${version}.schema.json"
47+
local STRICT_SCHEMA_FILE="$SCHEMA_PATH/bom-${version}-strict.schema.json"
2548
if [ -f "$STRICT_SCHEMA_FILE" ]
2649
then
2750
SCHEMA_FILE="$STRICT_SCHEMA_FILE"
2851
fi
2952
echo "SCHEMA_FILE: $SCHEMA_FILE"
3053

31-
OUT_FILE="$DOCS_PATH/$version/json/index.html"
32-
mkdir -p "$(dirname "$OUT_FILE")"
54+
local OUT_FILE="$DOCS_PATH/$version/json/index.html"
55+
local OUT_DIR="$(dirname "$OUT_FILE")"
56+
rm -rf "$OUT_DIR"
57+
mkdir -p "$OUT_DIR"
3358

3459
generate-schema-doc \
3560
--config no_link_to_reused_ref \
@@ -47,8 +72,42 @@ generate () {
4772
sed -i -e "s/\${version}/$version/g" "$OUT_FILE"
4873
}
4974

50-
generate 1.2
51-
generate 1.3
52-
generate 1.4
53-
generate 1.5
54-
generate 1.6
75+
76+
# Main logic to handle the argument using a switch case
77+
case "$#" in
78+
1)
79+
case "$1" in
80+
'-h'|'--help')
81+
echo "$DESC"
82+
echo "$USAGE"
83+
exit 0
84+
;;
85+
*) # One argument provided: Call generate with the specific version
86+
for version in "${CDX_VERSIONS[@]}"
87+
do
88+
if [[ "$1" == "$version" ]]
89+
then
90+
prepare
91+
generate "$1"
92+
exit 0
93+
fi
94+
done
95+
echo "Error: unknown CDX_VERSION: $1"
96+
echo "$USAGE"
97+
exit 1
98+
;;
99+
esac
100+
;;
101+
0) # No arguments provided: Loop over all
102+
for version in "${CDX_VERSIONS[@]}"
103+
do
104+
prepare
105+
generate "$version"
106+
done
107+
exit 0
108+
;;
109+
*) # More than one argument provided: Show usage help
110+
echo "Usage: $USAGE"
111+
exit 2
112+
;;
113+
esac

‎docgen/proto/gen.sh‎

Lines changed: 69 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,105 @@
11
#!/bin/bash
22
set -eu
33

4+
declare -a CDX_VERSIONS=(
5+
'1.6'
6+
'1.5'
7+
'1.4'
8+
'1.3'
9+
)
10+
11+
# region help
12+
DESC="Generate HTML Schema navigator for CycloneDX ProtoBuf"
13+
USAGE="
14+
Usage: $0 [CDX_VERSION...]
15+
16+
Supported values for CDX_VERSION: ${CDX_VERSIONS[*]}
17+
"
18+
# endregion help
19+
20+
421
THIS_PATH="$(realpath "$(dirname "$0")")"
522
SCHEMA_PATH="$(realpath "$THIS_PATH/../../schema")"
623
DOCS_PATH="$THIS_PATH/docs"
724
TEMPLATES_PATH="$THIS_PATH/templates"
825

926
PROTOC_GEN_DOC_VERSION='1.5.1'
1027

28+
1129
# --
1230

13-
rm -f -R "$DOCS_PATH"
31+
32+
prepare() {
33+
## docs: https://github.com/pseudomuto/protoc-gen-doc
34+
PROTOC_CONTAINER_IMAGE="pseudomuto/protoc-gen-doc:${PROTOC_GEN_DOC_VERSION}"
35+
docker pull "$PROTOC_CONTAINER_IMAGE"
36+
}
1437

1538
generate () {
16-
version="$1"
17-
title="CycloneDX v$version Protobuf Reference"
39+
local version="$1"
40+
local title="CycloneDX v$version Protobuf Reference"
1841
echo "Generating: $title"
1942

20-
OUT_DIR="$DOCS_PATH/$version/proto"
21-
OUT_FILE="index.html"
43+
local OUT_DIR="$DOCS_PATH/$version/proto"
44+
local OUT_FILE="index.html"
2245
mkdir -p "$OUT_DIR"
2346

24-
## docs: https://github.com/pseudomuto/protoc-gen-doc
2547
docker run --rm \
2648
-v "${OUT_DIR}:/out" \
2749
-v "${SCHEMA_PATH}:/protos:ro" \
2850
-v "${TEMPLATES_PATH}:/templates:ro" \
29-
"pseudomuto/protoc-gen-doc:${PROTOC_GEN_DOC_VERSION}" \
51+
"$PROTOC_CONTAINER_IMAGE" \
3052
--doc_opt=/templates/html.tmpl,"$OUT_FILE" \
3153
"bom-${version}.proto"
3254

3355
# fix file permissions
3456
docker run --rm \
3557
-v "${OUT_DIR}:/out" \
3658
--entrypoint chown \
37-
"pseudomuto/protoc-gen-doc:${PROTOC_GEN_DOC_VERSION}" \
59+
"$PROTOC_CONTAINER_IMAGE" \
3860
"$(id -u):$(id -g)" -R /out
3961

4062
sed -i -e "s/\${quotedTitle}/\"$title\"/g" "$OUT_DIR/$OUT_FILE"
4163
sed -i -e "s/\${title}/$title/g" "$OUT_DIR/$OUT_FILE"
4264
sed -i -e "s/\${version}/$version/g" "$OUT_DIR/$OUT_FILE"
4365
}
4466

45-
generate 1.3
46-
generate 1.4
47-
generate 1.5
48-
generate 1.6
67+
68+
# Main logic to handle the argument using a switch case
69+
case "$#" in
70+
1)
71+
case "$1" in
72+
'-h'|'--help')
73+
echo "$DESC"
74+
echo "$USAGE"
75+
exit 0
76+
;;
77+
*) # One argument provided: Call generate with the specific version
78+
for version in "${CDX_VERSIONS[@]}"
79+
do
80+
if [[ "$1" == "$version" ]]
81+
then
82+
prepare
83+
generate "$1"
84+
exit 0
85+
fi
86+
done
87+
echo "Error: unknown CDX_VERSION: $1"
88+
echo "$USAGE"
89+
exit 1
90+
;;
91+
esac
92+
;;
93+
0) # No arguments provided: Loop over all
94+
for version in "${CDX_VERSIONS[@]}"
95+
do
96+
prepare
97+
generate "$version"
98+
done
99+
exit 0
100+
;;
101+
*) # More than one argument provided: Show usage help
102+
echo "Usage: $USAGE"
103+
exit 2
104+
;;
105+
esac

‎docgen/xml/gen.sh‎

Lines changed: 73 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,55 @@
11
#!/bin/bash
22
set -eu
33

4+
declare -a CDX_VERSIONS=(
5+
'1.6'
6+
'1.5'
7+
'1.4'
8+
'1.3'
9+
'1.2'
10+
'1.1'
11+
'1.0'
12+
)
13+
14+
# region help
15+
DESC="Generate HTML Schema navigator for CycloneDX XML"
16+
USAGE="
17+
Usage: $0 [CDX_VERSION...]
18+
19+
Supported values for CDX_VERSION: ${CDX_VERSIONS[*]}
20+
"
21+
# endregion help
22+
23+
424
THIS_PATH="$(realpath "$(dirname "$0")")"
525
SCHEMA_PATH="$(realpath "$THIS_PATH/../../schema")"
626
DOCS_PATH="$THIS_PATH/docs"
727

828
SAXON_VERSION='10.9'
929

10-
# --
1130

12-
13-
rm -rf "$DOCS_PATH"
31+
# --
1432

1533

1634
SAXON_JAR="Saxon-HE-${SAXON_VERSION}.jar"
17-
if [ ! -f "$THIS_PATH/$SAXON_JAR" ]; then
18-
echo "fetching $SAXON_JAR"
19-
curl --output-dir "$THIS_PATH" -O \
20-
"https://repo1.maven.org/maven2/net/sf/saxon/Saxon-HE/$SAXON_VERSION/$SAXON_JAR"
21-
fi
35+
prepare () {
36+
if [ ! -f "$THIS_PATH/$SAXON_JAR" ]; then
37+
echo "fetching $SAXON_JAR"
38+
curl --output-dir "$THIS_PATH" -O \
39+
"https://repo1.maven.org/maven2/net/sf/saxon/Saxon-HE/$SAXON_VERSION/$SAXON_JAR"
40+
fi
41+
}
2242

2343

2444
generate () {
25-
version="$1"
26-
title="CycloneDX v$version XML Reference"
45+
local version="$1"
46+
local title="CycloneDX v$version XML Reference"
2747
echo "Generating: $title"
2848

29-
OUT_FILE="$DOCS_PATH/$version/xml/index.html"
30-
mkdir -p "$(dirname "$OUT_FILE")"
49+
local OUT_FILE="$DOCS_PATH/$version/xml/index.html"
50+
local OUT_DIR="$(dirname "$OUT_FILE")"
51+
rm -rf "$OUT_DIR"
52+
mkdir -p "$OUT_DIR"
3153

3254
## docs: https://www.saxonica.com/documentation10/index.html#!using-xsl/commandline
3355
java -jar "$THIS_PATH/$SAXON_JAR" \
@@ -38,10 +60,42 @@ generate () {
3860
title="$title"
3961
}
4062

41-
generate 1.0
42-
generate 1.1
43-
generate 1.2
44-
generate 1.3
45-
generate 1.4
46-
generate 1.5
47-
generate 1.6
63+
64+
# Main logic to handle the argument using a switch case
65+
case "$#" in
66+
1)
67+
case "$1" in
68+
'-h'|'--help')
69+
echo "$DESC"
70+
echo "$USAGE"
71+
exit 0
72+
;;
73+
*) # One argument provided: Call generate with the specific version
74+
for version in "${CDX_VERSIONS[@]}"
75+
do
76+
if [[ "$1" == "$version" ]]
77+
then
78+
prepare
79+
generate "$1"
80+
exit 0
81+
fi
82+
done
83+
echo "Error: unknown CDX_VERSION: $1"
84+
echo "$USAGE"
85+
exit 1
86+
;;
87+
esac
88+
;;
89+
0) # No arguments provided: Loop over all
90+
for version in "${CDX_VERSIONS[@]}"
91+
do
92+
prepare
93+
generate "$version"
94+
done
95+
exit 0
96+
;;
97+
*) # More than one argument provided: Show usage help
98+
echo "Usage: $USAGE"
99+
exit 2
100+
;;
101+
esac

0 commit comments

Comments
 (0)