elastic / elastic/crd-ref-docs
Support custom markers for packages out of `api/`
- 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
Assessment
This issue has not been assessed yet.