Generate API reference docs

[jlewi]

We should generate API reference docs for various aspects of Kubeflow; e.g our custom operators, the Katib API, Pipelines API.

Here are instructions for how Kubernetes generates its reference docs. Looks like its based on OpenAPI specs.
https://kubernetes.io/docs/contribute/generate-ref-docs/kubernetes-api/

Related issues:
kubeflow/katib#120 - Document Katib API
kubeflow/training-operator#731 - Document TFJob API

[sarahmaddox]

Here's the existing issue for the Pipelines reference: #345 - it includes some discussion.

[sarahmaddox]

We need to think about how we'll include the generated reference docs in our Kubeflow website.
As an example, see Kubernetes:

• Has a “Reference” page within the website framework, listing the various reference docs: https://kubernetes.io/docs/reference/
• Then branches out to a separate look and feel for the generated reference: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/

[sarahmaddox]

There's a REST API that you can use to, for example, create a new pipeline. Here is the swagger definition for the API:
https://github.com/kubeflow/pipelines/tree/master/backend/api/swagger

The Python SDK supports submitting pipeline runs programmatically:
https://github.com/kubeflow/pipelines/blob/master/sdk/python/kfp/_client.py

[sarahmaddox]

Useful discussion happening over here: kubeflow/training-operator#731

[jlewi]

Docs for TFJob are now generated; kubeflow/training-operator#731 is closed.

@sarahmaddox Is there more work to be done here or can we close this issue?

[sarahmaddox]

I'm not sure - are there any other APIs / CRDs we should generate references for? If so, perhaps we should create individual issues for those, and close this generic issue.

• We now have a framework in place to hold generated references.
• We've the created TFJob reference.
• We have a separate issue for the Pipelines reference: Create a reference guide for Kubeflow Pipelines #345

[jlewi]

SGTM. Lets close this issue and open up additional specific issues as needed.