forked from kubernetes/kubernetes
-
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 kubernetes#11357 from caesarxuchao/api-type-doc-to…
…ol-2 generate docs for types defined in pkg/api/v*/types.go
- Loading branch information
Showing
9 changed files
with
59,643 additions
and
0 deletions.
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
Large diffs are not rendered by default.
Oops, something went wrong.
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,17 @@ | ||
FROM java:7-jre | ||
|
||
RUN apt-get update | ||
RUN apt-get install -qq -y asciidoctor | ||
RUN apt-get install -qq -y unzip | ||
RUN wget https://services.gradle.org/distributions/gradle-2.5-bin.zip | ||
RUN mkdir build/ | ||
RUN unzip gradle-2.5-bin.zip -d build/ | ||
|
||
COPY build.gradle build/ | ||
COPY gen-swagger-docs.sh build/ | ||
|
||
#run the script once to download the dependent java libraries into the image | ||
RUN mkdir /output | ||
RUN build/gen-swagger-docs.sh https://raw.githubusercontent.com/GoogleCloudPlatform/kubernetes/master/api/swagger-spec/v1.json https://raw.githubusercontent.com/GoogleCloudPlatform/kubernetes/master/pkg/api/v1/register.go | ||
|
||
ENTRYPOINT ["build/gen-swagger-docs.sh"] |
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,18 @@ | ||
This folder contains the sources needed to build the gen-swagger-doc container. | ||
|
||
To build the container image, | ||
|
||
``` | ||
$ sudo docker build -t gcr.io/google_containers/gen-swagger-docs:v1 . | ||
``` | ||
|
||
To generate the html docs, | ||
|
||
``` | ||
$ ./run-gen-swagger-docs.sh <API version> <absolute output path, default to PWD> | ||
``` | ||
|
||
The generated definitions.html and operations.html will be stored in output paths. | ||
|
||
|
||
[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/hack/gen-swagger-doc/README.md?pixel)]() |
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,18 @@ | ||
buildscript { | ||
repositories { | ||
mavenLocal() | ||
jcenter() | ||
} | ||
|
||
dependencies { | ||
classpath 'io.github.robwin:swagger2markup:0.6.0' | ||
} | ||
} | ||
|
||
task gendocs << { | ||
io.github.robwin.swagger2markup.Swagger2MarkupConverter | ||
.from("./input.json") | ||
.build() | ||
.intoFolder("./"); | ||
println '*** generating docs to ./' | ||
} |
5,910 changes: 5,910 additions & 0 deletions
5,910
hack/gen-swagger-doc/example-output/definitions.html
Large diffs are not rendered by default.
Oops, something went wrong.
23,842 changes: 23,842 additions & 0 deletions
23,842
hack/gen-swagger-doc/example-output/operations.html
Large diffs are not rendered by default.
Oops, something went wrong.
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,62 @@ | ||
#!/bin/bash | ||
|
||
# Copyright 2014 The Kubernetes Authors All rights reserved. | ||
# | ||
# Licensed under the Apache License, Version 2.0 (the "License"); | ||
# you may not use this file except in compliance with the License. | ||
# You may obtain a copy of the License at | ||
# | ||
# http://www.apache.org/licenses/LICENSE-2.0 | ||
# | ||
# Unless required by applicable law or agreed to in writing, software | ||
# distributed under the License is distributed on an "AS IS" BASIS, | ||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
# See the License for the specific language governing permissions and | ||
# limitations under the License. | ||
|
||
# Script to generate docs from the latest swagger spec. | ||
|
||
set -o errexit | ||
set -o nounset | ||
set -o pipefail | ||
|
||
echo $1 | ||
echo $2 | ||
|
||
cd /build/ | ||
|
||
wget "$1" -O input.json | ||
wget "$2" -O register.go | ||
|
||
./gradle-2.5/bin/gradle gendocs --info | ||
|
||
#insert a TOC for top level API objects | ||
buf="== Top Level API Objects\n\n" | ||
top_level_models=$(grep IsAnAPIObject ./register.go | sed 's/func (\*\(.*\)) IsAnAPIObject/\1/g' \ | ||
| tr -d '()' | tr -d '{}' | tr -d ' ') | ||
for m in $top_level_models | ||
do | ||
if grep -xq "=== v1.$m" ./definitions.adoc | ||
then | ||
buf+="* <<v1."$m">>\n" | ||
fi | ||
done | ||
sed -i "1i $buf" ./definitions.adoc | ||
|
||
#fix the links in .adoc, replace <<x.y>> with link:definitions.html#_x_y[x.y], and lowercase the _x_y part | ||
sed -i -e 's|<<\(.*\)\.\(.*\)>>|link:#_\L\1_\2\E[\1.\2]|g' ./definitions.adoc | ||
sed -i -e 's|<<\(.*\)\.\(.*\)>>|link:definitions.html#_\L\1_\2\E[\1.\2]|g' ./paths.adoc | ||
|
||
#fix the link to <<any>> | ||
sed -i -e 's|<<any>>|link:#_any[any]|g' ./definitions.adoc | ||
sed -i -e 's|<<any>>|link:definitions.html#_any[any]|g' ./paths.adoc | ||
|
||
echo -e "=== any\nRepresents an untyped JSON map - see the description of the field for more info about the structure of this object." >> ./definitions.adoc | ||
|
||
asciidoctor definitions.adoc | ||
asciidoctor paths.adoc | ||
|
||
cp definitions.html /output/ | ||
cp paths.html /output/operations.html | ||
|
||
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,24 @@ | ||
#!/bin/bash | ||
|
||
# Copyright 2014 The Kubernetes Authors All rights reserved. | ||
# | ||
# Licensed under the Apache License, Version 2.0 (the "License"); | ||
# you may not use this file except in compliance with the License. | ||
# You may obtain a copy of the License at | ||
# | ||
# http://www.apache.org/licenses/LICENSE-2.0 | ||
# | ||
# Unless required by applicable law or agreed to in writing, software | ||
# distributed under the License is distributed on an "AS IS" BASIS, | ||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
# See the License for the specific language governing permissions and | ||
# limitations under the License. | ||
|
||
if [ "$#" -lt 1 ]; then | ||
echo "Usage: run-gen-swagger-docs.sh <API version> <absolute output path, default to PWD>" | ||
exit | ||
fi | ||
OUTPUT=${2:-${PWD}} | ||
|
||
docker run -v ${OUTPUT}:/output gcr.io/google_containers/gen-swagger-docs:v1 https://raw.githubusercontent.com/GoogleCloudPlatform/kubernetes/master/api/swagger-spec/$1.json https://raw.githubusercontent.com/GoogleCloudPlatform/kubernetes/master/pkg/api/$1/register.go | ||
|