elastic / elastic/crd-ref-docs

Support custom markers for packages out of `api/`

Open
#106 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
173
Forks
81
PR merge metrics
No merged PRs in 30d

Description

Hi team,

First of all, thank you for your work in maintaining this tool. It has been incredibly useful for our project.

I have a use case where my CRDs share common types that are defined outside of the `api/` package, as mentioned in issue #58.

While adding the `+groupName` and `+versionName` markers allows dependent packages to be included in the generated documentation, I've encountered a challenge. In my case, adding these k8s-related markers causes issues with internal tooling. Specifically, adding the `+versionName` marker breaks the functionality of `controller-tools`. As a result, this solution isn't feasible for my use case; thus, some of the fields in the generated crd docs are not pointing anywhere. Unless I miss something, there is no way for me to use another marker tag to specify the values read by `+groupName` and `+versionName` in dependent packages.

At the moment, the tool supports custom markers (this is how I overcame my issue). I was wondering if you would consider extending the functionality to allow the use of custom marker tag keys for `+groupName` and `+versionName`, as seen in the following section of the code: .

Instead of the following, which is also recognized by `controller-gen`:

```go
// +groupName=my.group.io
// +versionName=v1alpha1
package common
```

Perhaps we could implement custom markers like this:

```
// +mygrouptag=my.group.io
// +myversiontag=v1alpha1
package common
```

These custom tags (`+mygrouptag` and `+myversiontag`) could then be defined through the config file, as shown below:

```yaml
processor:
includePackages:
"github.com/myorg/my-operator/api/common": # Go package name
groupNameTag: "mygrouptag" # Custom tag for groupName
groupVersionTag: "myversiontag" # Custom tag for versionName
```

This would provide great flexibility. I already have a toy implementation I use => https://github.com/buraksekili/crd-ref-docs/commit/99f5b673e09f2220c2daeeb29341420c2b892bfa.

Regardless of the proposed solution, any suggestions or ideas to address this issue are most welcome.
Thank you!

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.