elastic / crd-ref-docs

Generates Kubernetes CRD API reference documentation
Apache License 2.0
103 stars 53 forks source link

String alias defined outside of package is not resolved #58

Closed RealAnna closed 8 months ago

RealAnna commented 11 months ago

How to reproduce:

have a common.go file with a simple string alias

i.e. type KeptnState string

import the alias in an API type. The generated docs point to nothing.

image

type KeptnWorkloadInstanceStatus struct {
    // PreDeploymentStatus indicates the current status of the KeptnWorkloadInstance's PreDeployment phase.
    // +kubebuilder:default:=Pending
    PreDeploymentStatus common.KeptnState `json:"preDeploymentStatus,omitempty"`

image

See the autogenerated table here KeptnState, and the type is here the alias is defined here

I think the problem may be due to this change here: https://github.com/elastic/crd-ref-docs/commit/365ecbe3898eee7d95858dba7e13d4903d2faefb

As a temporary solution we are changing type.tpl to

|{{ .Name }}{{ if .Type.IsAlias }}_{{ markdownRenderTypeLink .Type.UnderlyingType }}_{{else}}_{{ markdownRenderType .Type }}_{{ end }} | {{ template "type_members" . }} |

but the Underlying type is missing in the generated types so this is not a nice way to visualize it ...

tenstad commented 8 months ago

Reproduced in test project: https://github.com/tenstad/crd-ref-docs/commit/c187ae319b23ada9fd6bfc521009ba4f5e2cc376

tenstad commented 8 months ago

Parsing appears to be sane

image

tenstad commented 8 months ago

The package is skipped due to https://github.com/elastic/crd-ref-docs/blob/c62fbcdc507f62d81189874b017859c2f269e4b0/processor/processor.go#L164-L167

By adding group version info, the type is generated in documentation: https://github.com/elastic/crd-ref-docs/pull/66/commits/85c6ceec4530af89ab77431799782aa4a876bdb8

tenstad commented 8 months ago

@RealAnna can you try adding a +groupName marker on the package?

// +groupName=webapp.test.k8s.elastic.co
package common
RealAnna commented 8 months ago

@tenstad thanks for having a look at this, I will try!

RealAnna commented 8 months ago
// +groupName=lifecycle.keptn.sh
// +versionName=v1beta1
package common

worked like a charm! Thank you 😄!