forked from kubevirt/kubevirt
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request kubevirt#550 from lukas-bednar/docgen
Generate KubeVirt API Reference documentation
- Loading branch information
Showing
7 changed files
with
175 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| buildscript { | ||
| repositories { | ||
| mavenLocal() | ||
| jcenter() | ||
| } | ||
|
|
||
| dependencies { | ||
| classpath "io.github.swagger2markup:swagger2markup-gradle-plugin:1.3.1" | ||
| classpath "org.asciidoctor:asciidoctor-gradle-plugin:1.5.6" | ||
| } | ||
| } | ||
|
|
||
| apply plugin: 'io.github.swagger2markup' | ||
|
|
||
| convertSwagger2markup { | ||
| swaggerInput "./api/openapi-spec/swagger.json" | ||
| outputDir file("./") | ||
| config = [ | ||
| 'swagger2markup.markupLanguage': markupLanguage, | ||
| 'swagger2markup.interDocumentCrossReferencesEnabled': true, | ||
| ] | ||
| } | ||
|
|
||
| apply plugin: 'org.asciidoctor.convert' | ||
|
|
||
| asciidoctor { | ||
| sourceDir = file('./') | ||
| sources { | ||
| // paths.adoc is being renamed to operations.adoc by gen-swagger-docs.sh. | ||
| // Keeping it here in case somebody run: gradle convertSwagger2markup asciidoctor | ||
| include 'definitions.adoc', 'overview.adoc', 'paths.adoc', 'security.adoc', 'operations.adoc' | ||
| } | ||
| outputDir = file('./') | ||
| attributes 'toc' : 'right' | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| #!/usr/bin/env bash | ||
|
|
||
| set -e | ||
|
|
||
| GITHUB_FQDN=github.com | ||
| API_REF_REPO=kubevirt-incubator/api-reference | ||
| API_REF_DIR=/tmp/api-reference | ||
|
|
||
| git clone \ | ||
| "https://${API_REFERENCE_PUSH_TOKEN}@${GITHUB_FQDN}/${API_REF_REPO}.git" \ | ||
| "${API_REF_DIR}" > /dev/null 2>&1 | ||
| rm -rf "${API_REF_DIR}/content/"* | ||
| cp -f hack/gen-swagger-doc/html5/content/*.html "${API_REF_DIR}/content/" | ||
|
|
||
| cd "${API_REF_DIR}" | ||
|
|
||
| git config --global user.email "[email protected]" | ||
| git config --global user.name "Travis CI" | ||
|
|
||
| if git status --porcelain | grep --quiet "^ M" ; | ||
| then | ||
| git add -A content/*.html | ||
| git commit --message "API Reference update by Travis Build ${TRAVIS_BUILD_NUMBER}" | ||
|
|
||
| git push origin master > /dev/null 2>&1 | ||
| echo "API Reference updated." | ||
| else | ||
| echo "API Reference hasn't changed." | ||
| fi |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,91 @@ | ||
| #!/bin/bash | ||
|
|
||
| # gen-swagger-docs.sh $API_VERSION $OUTPUT_FORMAT | ||
| # API_VERSION=v1 | ||
| # OUTPUT_FORMAT=html|markdown | ||
|
|
||
| set -o errexit | ||
| set -o nounset | ||
| set -o pipefail | ||
|
|
||
| VERSION="${1:-v1}" | ||
| OUTPUT_FORMAT="${2:-html}" | ||
| if [ "$OUTPUT_FORMAT" = "html" ] ; | ||
| then | ||
| SUFFIX="adoc" | ||
| HEADER="=" | ||
| LINK1_TEMPLATE="\* \<\<\${VERSION}.\$m\>\>" | ||
| LINK_DEFINITIONS="* link:./definitions.html[Types Definition]" | ||
| LINK_OPERATIONS="* link:./operations.html[Operations]" | ||
| GRADLE_EXTRA_PARAMS="" | ||
| elif [ "$OUTPUT_FORMAT" = "markdown" ] ; | ||
| then | ||
| SUFFIX="md" | ||
| HEADER="#" | ||
| LINK1_TEMPLATE="\* [\${VERSION}.\$m]\(definitions.md#\${VERSION}-\${m,,}\)" | ||
| LINK_DEFINITIONS="* [Types Definition](definitions.md)" | ||
| LINK_OPERATIONS="* [Operations](operations.md)" | ||
| GRADLE_EXTRA_PARAMS="-PmarkupLanguage=MARKDOWN" | ||
| else | ||
| echo "Unknown OUTPUT_FORMAT=${OUTPUT_FORMAT}" | ||
| exit 1 | ||
| fi | ||
| WORKDIR="hack/gen-swagger-doc" | ||
| GRADLE_BUILD_FILE="$WORKDIR/build.gradle" | ||
|
|
||
|
|
||
| # Generate *.adoc files from swagger.json | ||
| gradle -b $GRADLE_BUILD_FILE $GRADLE_EXTRA_PARAMS convertSwagger2markup --info | ||
|
|
||
| #insert a TOC for top level API objects | ||
| buf="${HEADER}${HEADER} Top Level API Objects\n\n" | ||
| top_level_models=$(grep '&[A-Za-z]*{},' pkg/api/${VERSION}/types.go | sed 's/.*&//;s/{},//') | ||
|
|
||
| # check if the top level models exist in the definitions.$SUFFIX. If they exist, | ||
| # their name will be <version>.<model_name> | ||
| for m in $top_level_models | ||
| do | ||
| if grep -xq "${HEADER}${HEADER}${HEADER} ${VERSION}.$m" "$WORKDIR/definitions.${SUFFIX}" | ||
| then | ||
| buf+="$(eval echo $LINK1_TEMPLATE)\n" | ||
| fi | ||
| done | ||
| sed -i "1i $buf" "$WORKDIR/definitions.${SUFFIX}" | ||
|
|
||
| # change the title of paths.adoc from "paths" to "operations" | ||
| sed -i "s|${HEADER}${HEADER} Paths|${HEADER}${HEADER} Operations|g" "$WORKDIR/paths.${SUFFIX}" | ||
| mv -f "$WORKDIR/paths.${SUFFIX}" "$WORKDIR/operations.${SUFFIX}" | ||
|
|
||
|
|
||
| # Add links to definitons & operations under overview | ||
| cat >> "$WORKDIR/overview.${SUFFIX}" << __END__ | ||
| ${HEADER}${HEADER} KubeVirt API Reference | ||
| ${LINK_DEFINITIONS} | ||
| ${LINK_OPERATIONS} | ||
| __END__ | ||
|
|
||
|
|
||
| if [ "$OUTPUT_FORMAT" = "html" ] ; | ||
| then | ||
| # $$ has special meaning in asciidoc, we need to escape it | ||
| sed -i 's|\$\$|+++$$+++|g' "$WORKDIR/definitions.adoc" | ||
| sed -i '1 i\:last-update-label!:' "$WORKDIR/"*.adoc | ||
|
|
||
| # Generate *.html files from *.adoc | ||
| gradle -b $GRADLE_BUILD_FILE asciidoctor --info | ||
| rm -rf "$WORKDIR/html5/content" && mkdir "$WORKDIR/html5/content" && mv -f "$WORKDIR/html5/"*.html "$WORKDIR/html5/content" | ||
| mv -f "$WORKDIR/html5/content/overview.html" "$WORKDIR/html5/content/index.html" | ||
| elif [ "$OUTPUT_FORMAT" = "markdown" ] ; | ||
| then | ||
| # Generate TOC for definitions & operations as README.md | ||
| cd "$WORKDIR" | ||
| echo "# KubeVirt API Reference" > README.md | ||
| curl \ | ||
| https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc | \ | ||
| bash -s "definitions.md" "operations.md" | \ | ||
| sed 's/^ //' >> "README.md" | ||
| cd - | ||
| fi | ||
|
|
||
| echo "SUCCESS" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| markupLanguage=ASCIIDOC |