Add MPIJob v1alpha2 API reference

[terrytangyuan]

Part of kubeflow/mpi-operator#217.

Signed-off-by: terrytangyuan [email protected]

[kubeflow-bot]

This change is 

[terrytangyuan]

Trying to following instruction here but seeing the error below. Does anyone know how to fix it? What version of gen-crd-api-reference-docs have we used to generate the existing docs?

I0415 12:57:05.106541   52177 main.go:123] parsing go packages in directory github.com/kubeflow/mpi-operator/pkg/apis/kubeflow/v1alpha2
I0415 12:57:05.618382   52177 main.go:225] using package=github.com/kubeflow/mpi-operator/pkg/apis/kubeflow/v1alpha2
F0415 12:57:05.646690   52177 main.go:444] type invalid type has kind=Unsupported which is unhandled

[terrytangyuan]

cc'ing folks that modified the docs recently @richardsliu @kbhawkey @rlenferink

[kbhawkey]

Hello @terrytangyuan . A couple of questions:

• What type is the script failing on, https://github.com/ahmetb/gen-crd-api-reference-docs/blob/master/main.go#L457
• I suggest that you try the gen-crd-api-reference-docs program from the command line before running in the script.

[terrytangyuan]

Looks like these issues might be related:

• Knative gen-api-reference-docs.sh fail for knative/serving api v0.8 ahmetb/gen-crd-api-reference-docs#10
• Can not generate projects that uses go module ahmetb/gen-crd-api-reference-docs#12

Are there other alternatives for API doc generation?

[kbhawkey]

Ping @sarahmaddox

[sarahmaddox]

/assign @richardsliu

@richardsliu Do you have any guidance to give here?

[richardsliu]

@zhenghuiwang How did you work around this issue?

[zhenghuiwang]

@terrytangyuan FYI this is a workaround I tried last time for generating notebook controller API references.

[terrytangyuan]

Yea I read that and tried something similar - still no luck. Would it be permitted to add the docs manually? There seems to be more work working around the issues than manually writing up the docs. As we aim to graduate v1 API of MPIJob, the API should stay relatively stable so there won't be that much effort updating it later on.

[sarahmaddox]

FYI, please note that you'll need to move the files in this PR, due to PR #1909, which inserted the /en/ element into the directory path for all content files. In other words, that PR moved all content files from content/docs/... to content/en/docs/....

[terrytangyuan]

@sarahmaddox Thanks for the note.

The problem right now is that the gen-crd-api-reference-docs tool is either not working or requires specific hack/fix for different controllers/projects. It would be good if someone from your team or from community can put together an alternative solution. Otherwise the API docs are not maintainable. To avoid blocking the graduation of operators, we may just add docs manually.

[sarahmaddox]

@terrytangyuan Thanks for the info. +1 to adding the MPIJob API reference manually for now. Looking at the reports on the various issues, it looks as if others are resorting to the same strategy until the gen-crd-api-reference-docs tool is fixed.

At this point, I think it's worth waiting a while to see if the gen-crd-api-reference-docs bugs get fixed, rather than creating an alternative solution for Kubeflow. But if someone in the community has the bandwidth and knowledge to create an alternative, that would be great too. @terrytangyuan can you create an issue in kubeflow/website, summarizing the problem, giving the current status, asking if anyone would like to develop an alternative tool, and linking to the relevant info:

• This PR (Add MPIJob v1alpha2 API reference #1899)
• notebook controller API reference docs kubeflow#3723 (comment)
• Knative gen-api-reference-docs.sh fail for knative/serving api v0.8 ahmetb/gen-crd-api-reference-docs#10
• Can not generate projects that uses go module ahmetb/gen-crd-api-reference-docs#12

With that issue, we'll have one convenient place to point people too, and it will also provide the opportunity for someone to create the fix if they want to contribute in that way.

[terrytangyuan]

@sarahmaddox Thanks! I created an issue in #1924. I'll update this PR later with manually generated API docs for MPIJob if it's not fixed by then.

[terrytangyuan]

@sarahmaddox I have added the API reference docs manually. Please take a look when you get a chance.

[sarahmaddox]

/unassign @richardsliu
/assign

[sarahmaddox]

Preview:

• https://deploy-preview-1899--competent-brattain-de2d6d.netlify.app/docs/reference/overview/
• https://deploy-preview-1899--competent-brattain-de2d6d.netlify.app/docs/reference/mpijob/
• https://deploy-preview-1899--competent-brattain-de2d6d.netlify.app/docs/reference/mpijob/v1alpha2/
• https://deploy-preview-1899--competent-brattain-de2d6d.netlify.app/docs/reference/mpijob/v1alpha2/mpi/

[sarahmaddox]

Thanks @terrytangyuan!
/lgtm
/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: sarahmaddox

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [sarahmaddox]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment