The current tool for API docs generation is unusable

[terrytangyuan]

The current tool we use, gen-crd-api-reference-docs, is unusable right now for updating existing API reference docs or generating new API reference for new controllers. We need to fix the existing issues or create an alternative solution. A couple of existing issues are outlined below:

• The obscure error message type invalid type has kind=Unsupported which is unhandled appears in Add MPIJob v1alpha2 API reference #1899 (comment) and Knative gen-api-reference-docs.sh fail for knative/serving api v0.8 ahmetb/gen-crd-api-reference-docs#10.
• This tool does not support Go Modules yet as mentioned in Can not generate projects that uses go module ahmetb/gen-crd-api-reference-docs#12 and notebook controller API reference docs kubeflow#3723 (comment).
• Hacky workarounds are required for generating API reference docs for new controllers as discussed in notebook controller API reference docs kubeflow#3723. It will be impossible to maintain and non-trivial to reuse for generating docs for new controllers.

If anyone would like to fix the issues mentioned above or create an alternative solution, please comment on this issue.

Also cc'ing a few folks who were part of the discussion in #1899:
@sarahmaddox @zhenghuiwang @kbhawkey @rlenferink

[issue-label-bot]

Issue-Label Bot is automatically applying the labels:

Label	Probability
kind/bug	0.74

Please mark this comment with 👍 or 👎 to give our bot feedback!
Links: app homepage, dashboard and code for this bot.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[terrytangyuan]

This should not be closed. We need a solution for this.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[terrytangyuan]

/remove-lifecycle

[kbhawkey]

Hi @terrytangyuan .
You may be interested in this new tool, https://github.com/tengqm/genref.
I have not read through the changes, but thought it may help to generate docs for a controller API.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.