Fix external links on API doc, add default values

Support for default values was added in elastic/crd-ref-docs@9a3105b
but templating support is not complete yet.
We will probably revisit this when a new release of crd-ref-docs is out.

Change-Id: I24e420808152da563ce01365d5371618747ae61b

config/crd/bases/sf.softwarefactory-project.io_logservers.yaml

@@ -54,7 +54,7 @@ spec:
                 properties:
                   server:
                     description: 'Specify the Lets encrypt server. Valid values are:
-                      - "staging" - "prod"'
+                      "staging", "prod"'
                     enum:
                     - prod
                     - staging
@@ -96,8 +96,8 @@ spec:
                         anyOf:
                         - type: integer
                         - type: string
-                        description: 'Storage space to allocate to the resource, expressed
-                          as a Quantity: https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/'
+                        description: Storage space to allocate to the resource, expressed
+                          as a [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/)
                         pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
                         x-kubernetes-int-or-string: true
                     required:

doc/_apidoc/templates/gv_details.tpl

@@ -0,0 +1,19 @@
+{{- define "gvDetails" -}}
+{{- $gv := . -}}
+
+## {{ $gv.GroupVersionString }}
+
+{{ $gv.Doc }}
+
+{{- if $gv.Kinds  }}
+### Resource Types
+{{- range $gv.SortedKinds }}
+- {{ $gv.TypeForKind . | markdownRenderTypeLink }}
+{{- end }}
+{{ end }}
+
+{{ range $gv.SortedTypes }}
+{{ template "type" . }}
+{{ end }}
+
+{{- end -}}

doc/_apidoc/templates/gv_list.tpl

@@ -0,0 +1,15 @@
+{{- define "gvList" -}}
+{{- $groupVersions := . -}}
+
+# API Reference
+
+## Packages
+{{- range $groupVersions }}
+- {{ markdownRenderGVLink . }}
+{{- end }}
+
+{{ range $groupVersions }}
+{{ template "gvDetails" . }}
+{{ end }}
+
+{{- end -}}

doc/_apidoc/templates/type.tpl

@@ -0,0 +1,33 @@
+{{- define "type" -}}
+{{- $type := . -}}
+{{- if markdownShouldRenderType $type -}}
+
+#### {{ $type.Name }}
+
+{{ if $type.IsAlias }}_Underlying type:_ _{{ markdownRenderTypeLink $type.UnderlyingType  }}_{{ end }}
+
+{{ $type.Doc }}
+
+{{ if $type.References -}}
+_Appears in:_
+{{- range $type.SortedReferences }}
+- {{ markdownRenderTypeLink . }}
+{{- end }}
+{{- end }}
+
+{{ if $type.Members -}}
+| Field | Description | Default Value |
+| --- | --- | --- |
+{{ if $type.GVK -}}
+| `apiVersion` _string_ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}` | - |
+| `kind` _string_ | `{{ $type.GVK.Kind }}` | - |
+{{ end -}}
+
+{{ range $type.Members -}}
+| `{{ .Name  }}` _{{ markdownRenderType .Type }}_ | {{ template "type_members" . }} | {{ if eq .Name "logLevel" -}}INFO{{ else if index .Markers "kubebuilder:default" -}}{{ index .Markers "kubebuilder:default" 0 }}{{- else -}}-{{ end -}} |
+{{ end -}}
+
+{{ end -}}
+
+{{- end -}}
+{{- end -}}

doc/_apidoc/templates/type_member.tpl

@@ -0,0 +1,8 @@
+{{- define "type_members" -}}
+{{- $field := . -}}
+{{- if eq $field.Name "metadata" -}}
+Refer to Kubernetes API documentation for fields of `metadata`.
+{{- else -}}
+{{ markdownRenderFieldDoc $field.Doc }}
+{{- end -}}
+{{- end -}}

tools/build-api-doc.sh

@@ -31,14 +31,15 @@ git clone --depth=1 "file://${REPO_ROOT}" "$GITDIR"
 pushd "$GITDIR"
 # go mod vendor
 
-go get github.com/elastic/crd-ref-docs
+go get github.com/elastic/crd-ref-docs@master
 go install github.com/elastic/crd-ref-docs
 
 mkdir -p "${docstmpdir}/apidocs/"
 ${GOBIN}/crd-ref-docs \
     --config "${DOC_ROOT}/_apidoc/config.yaml" \
     --source-path "./api" \
     --output-path "${docstmpdir}/apidocs/index.md" \
+    --templates-dir "${DOC_ROOT}/_apidoc/templates" \
     --renderer=markdown
 
 popd