notebook controller API reference docs

[jlewi]

We need to publish API reference docs for the notebook controller as part of going beta and eventually 1.0.

See go/tf-operator-1-0

[issue-label-bot]

Issue-Label Bot is automatically applying the label improvement/enhancement to this issue, with a confidence of 0.66. Please mark this comment with 👍 or 👎 to give our bot feedback!

Links: app homepage, dashboard and code for this bot.

[jlewi]

Bump to P1 because this is needed for 1.0.

The docs should be published here:
https://www.kubeflow.org/docs/reference/

It looks like the existing docs are generated using
gen-crd-api-reference-docs

[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.

[jlewi]

Bump to P0 because its required for 1.0.

[zhenghuiwang]

Tried the same tool for generating TF1.0 ref doc, but failed. ahmetb/gen-crd-api-reference-docs#12 (comment)

[jlewi]

/lifecycle frozen

[zhenghuiwang]

We can't auto gen docs following this guide now. Summarizing the problems and a workaround:

Problems

1. The gen-crd-api-reference-docs tool doesn't work well with go module. Specifically it doesn't recognize the replace statement in go module, such as

replace github.com/kubeflow/kubeflow/components/common => ../common

which is common in kubeflow/kubeflow.

2. Current version of kubernetes/gengo stops generating doc.go, which gen-crd-api-docs tool still relies on. (see more discussion at [wip] Add support for kubebuilder v2 ahmetb/gen-crd-api-reference-docs#15 (comment)) (It is a non-trivial fix of the doc tool to me)

Workaround

1. Create a new Go package for your target CRD api package, e.g. (I created https://github.com/zhenghuiwang/nbctrler to clone kubeflow/components/notebook-controller)
2. Remove all replace statement in go.mod.

If your target go.mod doesn't have replace statement, you can skip step 1,2.

3. Manually create doc.go with these comments:

// Package v1 contains API Schema definitions for the kubeflow.org v1 API group
// +kubebuilder:object:generate=true
// +groupName=kubeflow.org
package v1

4. Download the gen-doc tool and run command like this to gen doc locally.

./gen-crd-api-reference-docs -config /Users/zhenghui/kubeflow/website/gen-api-reference/kubeflow-config.json -api-dir "github.com/zhenghuiwang/nbctrler/api/v1" -out-file tmp_notebook.md

/cc @richardsliu @kunmingg @abhi-g

[abhi-g]

Thanks Zhenghui for finding a workaround!

…

On Wed, Feb 12, 2020 at 12:09 PM Zhenghui Wang ***@***.***> wrote: We can't auto gen docs following this guide <https://github.com/kubeflow/website/tree/master/gen-api-reference> now. Summarizing the problems and a workaround: *Problems* 1. The gen-crd-api-reference-docs <https://github.com/ahmetb/gen-crd-api-reference-docs> tool doesn't work well with go module. Specifically it doesn't recognize the replace statement in go module, such as replace github.com/kubeflow/kubeflow/components/common => ../common which is common in kubeflow/kubeflow. 1. Current version of kubernetes/gengo stops generating doc.go, which gen-crd-api-docs tool still relies on. (see more discussion at ahmetb/gen-crd-api-reference-docs#15 (comment) <ahmetb/gen-crd-api-reference-docs#15 (comment)> ) *Workaround* 1. Create a new Go package for your target CRD api package, e.g. (I created https://github.com/zhenghuiwang/nbctrler to clone kubeflow/components/notebook-controller) 2. Remove all replace statement in go.mod. If your target go.mod doesn't have replace statement, you can skip step 1,2. 1. Manually create doc.go with these comments: // Package v1 contains API Schema definitions for the kubeflow.org v1 API group // +kubebuilder:object:generate=true // +groupName=kubeflow.org package v1 1. Download the gen-doc tool and run command like this to gen doc locally. ./gen-crd-api-reference-docs -config /Users/zhenghui/kubeflow/website/gen-api-reference/kubeflow-config.json -api-dir "github.com/zhenghuiwang/nbctrler/api/v1" -out-file tmp_notebook.md /cc @richardsliu <https://github.com/richardsliu> @kunmingg <https://github.com/kunmingg> @abhi-g <https://github.com/abhi-g> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#3723?email_source=notifications&email_token=ACZ2UZWP5EANY4FSYYO6KY3RCRJQRA5CNFSM4IF7AOPKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOELSGVZQ#issuecomment-585394918>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACZ2UZUA76DACPLXGPQRFHLRCRJQRANCNFSM4IF7AOPA> .