You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by dj...@apache.org on 2022/01/31 16:21:09 UTC
[camel-k] 02/05: update gen_crd_api script/config to use go run and asciidoc config
This is an automated email from the ASF dual-hosted git repository.
djencks pushed a commit to branch release-1.8.x
in repository https://gitbox.apache.org/repos/asf/camel-k.git
commit 17f2783e344e279de6c9a18c8e114afc1059aa2a
Author: David Jencks <dj...@apache.org>
AuthorDate: Thu Jan 20 20:47:52 2022 -0800
update gen_crd_api script/config to use go run and asciidoc config
add /github.com to .gitignore, it's similar to /vendor
use AsciiDoc API templates
---
.gitignore | 1 +
script/gen_crd/gen-crd-api-config.json | 3 +-
...onfig.json => gen-kamelets-crd-api-config.json} | 7 +-
script/gen_crd/gen_crd_api.sh | 31 ++++-----
script/gen_crd/template/members.tpl | 70 ++++++++-----------
script/gen_crd/template/pkg.tpl | 67 ++++++++-----------
script/gen_crd/template/type.tpl | 78 ++++++++--------------
7 files changed, 103 insertions(+), 154 deletions(-)
diff --git a/.gitignore b/.gitignore
index 6a7118a..dfa66a7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
# Go vendor
/vendor
+/github.com
# Binary files
/kamel
diff --git a/script/gen_crd/gen-crd-api-config.json b/script/gen_crd/gen-crd-api-config.json
index 5e4031c..1a6ae0d 100644
--- a/script/gen_crd/gen-crd-api-config.json
+++ b/script/gen_crd/gen-crd-api-config.json
@@ -17,5 +17,6 @@
"k8s.io/api/": "Kubernetes ",
"k8s.io/apimachinery/pkg/apis/": "Kubernetes "
},
- "markdownDisabled": false
+ "markdownDisabled": true,
+ "asciiDoc": true
}
diff --git a/script/gen_crd/gen-crd-api-config.json b/script/gen_crd/gen-kamelets-crd-api-config.json
similarity index 71%
copy from script/gen_crd/gen-crd-api-config.json
copy to script/gen_crd/gen-kamelets-crd-api-config.json
index 5e4031c..0e67016 100644
--- a/script/gen_crd/gen-crd-api-config.json
+++ b/script/gen_crd/gen-kamelets-crd-api-config.json
@@ -11,11 +11,16 @@
{
"typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/",
"docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
+ },
+ {
+ "typeMatchPrefix": "^github\\.com/apache/camel-k/pkg/apis/camel/v1\\.",
+ "docsURLTemplate": "xref:apis/camel-k.adoc#_camel_apache_org_v1_{{.TypeIdentifier}}"
}
],
"typeDisplayNamePrefixOverrides": {
"k8s.io/api/": "Kubernetes ",
"k8s.io/apimachinery/pkg/apis/": "Kubernetes "
},
- "markdownDisabled": false
+ "markdownDisabled": true,
+ "asciiDoc": true
}
diff --git a/script/gen_crd/gen_crd_api.sh b/script/gen_crd/gen_crd_api.sh
index 77f2f97..f4d696f 100755
--- a/script/gen_crd/gen_crd_api.sh
+++ b/script/gen_crd/gen_crd_api.sh
@@ -17,26 +17,23 @@
location=$(dirname $0)
rootdir=$location/../..
-crd_file=$rootdir/docs/modules/ROOT/partials/apis/crds-html.adoc
-
-echo "Downloading gen-crd-api-reference-docs binary..."
-TMPFILE=`mktemp`
-TMPDIR=`mktemp -d`
-PWD=`pwd`
-# TODO detect proper binary, based on the OS running this script
-wget -v https://github.com/ahmetb/gen-crd-api-reference-docs/releases/download/v0.1.5/gen-crd-api-reference-docs_linux_amd64.tar.gz -O $TMPFILE
-tar -C $TMPDIR -xf $TMPFILE
+crd_file_camel=$rootdir/docs/modules/ROOT/partials/apis/camel-k-crds.adoc
+crd_file_kamelets=$rootdir/docs/modules/ROOT/partials/apis/kamelets-crds.adoc
echo "Generating CRD API documentation..."
-$TMPDIR/gen-crd-api-reference-docs \
+# to run a local copy use something like
+#go run /Users/david/projects/camel/gen-crd-api-reference-docs/main.go \
+#you will probably need to comment out use of blackfriday.
+go run github.com/djencks/gen-crd-api-reference-docs@7400a10b36d7cfa7563ea48ce0df15a9d4c2de87 \
-config $location/gen-crd-api-config.json \
-template-dir $location/template \
- -api-dir "github.com/apache/camel-k/pkg/apis/camel" \
- -out-file $crd_file
+ -api-dir "github.com/apache/camel-k/pkg/apis/camel/v1" \
+ -out-file $crd_file_camel
-# Workaround: https://github.com/ahmetb/gen-crd-api-reference-docs/issues/33
-sed -i -E "s/%2f/\//" $crd_file
+go run github.com/djencks/gen-crd-api-reference-docs@7400a10b36d7cfa7563ea48ce0df15a9d4c2de87 \
+ -config $location/gen-kamelets-crd-api-config.json \
+ -template-dir $location/template \
+ -api-dir "github.com/apache/camel-k/pkg/apis/camel/v1alpha1" \
+ -out-file $crd_file_kamelets
-echo "Cleaning the gen-crd-api-reference-docs binary..."
-rm $TMPFILE
-rm -rf $TMPDIR
+echo "Generating CRD API documentation... Done."
diff --git a/script/gen_crd/template/members.tpl b/script/gen_crd/template/members.tpl
index a529c67..5771f11 100644
--- a/script/gen_crd/template/members.tpl
+++ b/script/gen_crd/template/members.tpl
@@ -1,48 +1,30 @@
-{{ define "members" }}
+{{ define "members" -}}
-{{ range .Members }}
-{{ if not (hiddenMember .)}}
-<tr>
- <td>
- <code>{{ fieldName . }}</code><br/>
- <em>
- {{ if linkForType .Type }}
- <a href="{{ linkForType .Type}}">
- {{ typeDisplayName .Type }}
- </a>
- {{ else }}
- {{ typeDisplayName .Type }}
- {{ end }}
- </em>
- </td>
- <td>
- {{ if fieldEmbedded . }}
- <p>
- (Members of <code>{{ fieldName . }}</code> are embedded into this type.)
- </p>
- {{ end}}
+{{ range .Members -}}
+ {{- if not (hiddenMember .) -}}
+|`{{ fieldName . }}` +
+{{ if linkForType .Type -}}
+ {{- if isLocalType .Type -}}
+*xref:{{ linkForType .Type}}[{{ asciiDocAttributeEscape (typeDisplayName .Type) }}]*
+ {{- else -}}
+*{{ linkForType .Type}}[{{ asciiDocAttributeEscape (typeDisplayName .Type) }}]*
+ {{- end -}}
+{{- else -}}
+ {{- typeDisplayName .Type -}}
+{{- end }}
+|{{ if fieldEmbedded . -}}
+(Members of `{{ fieldName . }}` are embedded into this type.)
+{{- end }}
+{{ if isOptionalMember . -}}
+*(Optional)*
+{{- end }}
- {{ if isOptionalMember .}}
- <em>(Optional)</em>
- {{ end }}
+{{ renderComments .CommentLines }}
- {{ safe (renderComments .CommentLines) }}
+{{ if and (eq (.Type.Name.Name) "ObjectMeta") -}}
+Refer to the Kubernetes API documentation for the fields of the `metadata` field.
+{{ end -}}
+{{- end -}}
+{{- end -}}
- {{ if and (eq (.Type.Name.Name) "ObjectMeta") }}
- Refer to the Kubernetes API documentation for the fields of the
- <code>metadata</code> field.
- {{ end }}
-
- {{ if or (eq (fieldName .) "spec") }}
- <br/>
- <br/>
- <table>
- {{ template "members" .Type }}
- </table>
- {{ end }}
- </td>
-</tr>
-{{ end }}
-{{ end }}
-
-{{ end }}
+{{- end }}
diff --git a/script/gen_crd/template/pkg.tpl b/script/gen_crd/template/pkg.tpl
index 220f015..c0cb3b4 100644
--- a/script/gen_crd/template/pkg.tpl
+++ b/script/gen_crd/template/pkg.tpl
@@ -1,43 +1,32 @@
-{{ define "packages" }}
-
-{{ with .packages}}
-<p>Packages:</p>
-<ul>
- {{ range . }}
- <li>
- <a href="#{{- packageAnchorID . -}}">{{ packageDisplayName . }}</a>
- </li>
- {{ end }}
-</ul>
-{{ end}}
-
-{{ range .packages }}
- <h2 id="{{- packageAnchorID . -}}">
- {{- packageDisplayName . -}}
- </h2>
-
- {{ with (index .GoPackages 0 )}}
- {{ with .DocComments }}
- <div>
- {{ safe (renderComments .) }}
- </div>
- {{ end }}
- {{ end }}
-
- Resource Types:
- <ul>
+{{ define "packages" -}}
+{{ range .packages -}}
+
+[#{{ packageAnchorID . }}]
+== {{ packageDisplayName . }}
+
+ {{- with (index .GoPackages 0 ) -}}
+ {{- with .DocComments }}
+
+{{ renderComments . }}
+ {{- end -}}
+ {{- end }}
+
+== Resource Types
+
+ {{- range (visibleTypes (sortedTypes .Types)) -}}
+ {{- if isExportedType . -}}
+ {{- template "type" . }}
+ {{- end -}}
+ {{- end }}
+
+== Internal Types
+
{{- range (visibleTypes (sortedTypes .Types)) -}}
- {{ if isExportedType . -}}
- <li>
- <a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
- </li>
- {{- end }}
+ {{- if not (isExportedType .) -}}
+ {{- template "type" . }}
+ {{- end -}}
{{- end -}}
- </ul>
- {{ range (visibleTypes (sortedTypes .Types))}}
- {{ template "type" . }}
- {{ end }}
-{{ end }}
+{{- end -}}
-{{ end }}
+{{- end }}
diff --git a/script/gen_crd/template/type.tpl b/script/gen_crd/template/type.tpl
index 725d405..d6f0dcf 100644
--- a/script/gen_crd/template/type.tpl
+++ b/script/gen_crd/template/type.tpl
@@ -1,58 +1,32 @@
{{ define "type" }}
-<h3 id="{{ anchorIDForType . }}">
- {{- .Name.Name }}
- {{ if eq .Kind "Alias" }}(<code>{{.Underlying}}</code> alias){{ end -}}
-</h3>
-{{ with (typeReferences .) }}
- <p>
- (<em>Appears on:</em>
- {{- $prev := "" -}}
- {{- range . -}}
- {{- if $prev -}}, {{ end -}}
- {{ $prev = . }}
- <a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
- {{- end -}}
- )
- </p>
-{{ end }}
+[#{{ anchorIDForType . }}]
+=== {{ .Name.Name }}{{ if eq .Kind "Alias" }}(`{{.Underlying}}` alias){{ end }}
+{{- with (typeReferences .) }}
+*Appears on:*
+{{ range . }}
+* <<{{ linkForType . }}, {{ typeDisplayName . }}>>
+{{- end -}}
+{{- end }}
-<div>
- {{ safe (renderComments .CommentLines) }}
-</div>
-
+{{ renderComments .CommentLines }}
{{ if .Members }}
-<table>
- <thead>
- <tr>
- <th>Field</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- {{ if isExportedType . }}
- <tr>
- <td>
- <code>apiVersion</code></br>
- string</td>
- <td>
- <code>
- {{apiGroup .}}
- </code>
- </td>
- </tr>
- <tr>
- <td>
- <code>kind</code></br>
- string
- </td>
- <td><code>{{.Name.Name}}</code></td>
- </tr>
- {{ end }}
- {{ template "members" .}}
- </tbody>
-</table>
-{{ end }}
+[cols="2,2a",options="header"]
+|===
+|Field
+|Description
+{{ if isExportedType . }}
+|`apiVersion` +
+string
+|`{{apiGroup .}}`
+
+|`kind` +
+string
+|`{{.Name.Name}}`
+{{- end }}
+{{ template "members" . }}
+|===
+{{- end -}}
-{{ end }}
+{{- end -}}