Katib v1beta1 documentation update #2312

andreyvelich · 2020-10-26T17:31:51Z

Related: kubeflow/katib#1360.
Blocked by: kubeflow/manifests#1593.
I updated docs for Katib v1beta1. I made few changes:

Update reference docs for v1beta1. @8bitmp3 @RFMVasconcelos Do we want to have v1alpha3 reference since all docs are written for v1beta1 ?
Fix few broken links.
Rename hyperparameter-tuning section to katib to make it clearer, since we are building AutoML project. What do you think about it @8bitmp3 @RFMVasconcelos ?
Add missing links for the examples, controller components, etc.
Update images.

I am still waiting for the pending PRs (I need to update docker images and few UI images., but it would be great if you can start to review it!

/assign @gaocegege @johnugeorge
/cc @8bitmp3 @RFMVasconcelos

kubeflow-bot · 2020-10-26T17:32:01Z

This change is

rui-vas · 2020-10-28T14:10:35Z

Hi @andreyvelich !

Thank you for this update! Replying by point:

Update reference docs for v1beta1. @8bitmp3 @RFMVasconcelos Do we want to have v1alpha3 reference since all docs are written for v1beta1 ?

You're asking if we want to keep a v1alpha3 version of the docs, now that we're updating Katib to v1beta1, correct?
If so:

When will these docs be effective? If we're launching v1beta1 with Kubeflow v1.2, would it make sense to include this in v1.2 of the docs?
If so, we can simply add a reference to v1alpha3 saying that docs can be found in Kubeflow v1.1 docs (with a link)

WDYT?

Rename hyperparameter-tuning section to katib to make it clearer, since we are building AutoML project. What do you think about it @8bitmp3 @RFMVasconcelos ?

LGTM.

rui-vas

One other point was the name change from Katib to something else. If we plan to do that, should we already make changes accordingly?

Any decision on that front?

andreyvelich · 2020-10-28T16:08:18Z

Thank you for the comment @RFMVasconcelos!

You're asking if we want to keep a v1alpha3 version of the docs, now that we're updating Katib to v1beta1, correct?
If so:

When will these docs be effective? If we're launching v1beta1 with Kubeflow v1.2, would it make sense to include this in v1.2 of the docs?

These docs will be effective after we merge: kubeflow/manifests#1593.
Including docs in V1.2 makes sense to me. I assume that website master branch will be point to 1.2 Kubeflow release, right ? If so, I am writing these docs to the appropriate branch.

If so, we can simply add a reference to v1alpha3 saying that docs can be found in Kubeflow v1.1 docs (with a link)

I think, it's a good idea. I will add v1alpha3 reference docs and add link to 1.1. Is there any way to get link for 1.1 docs? I found only 1.0 link: https://v1-0-branch.kubeflow.org/.

andreyvelich · 2020-10-28T16:10:43Z

One other point was the name change from Katib to something else. If we plan to do that, should we already make changes accordingly?

Any decision on that front?

I think we can stick with Katib name for Kubeflow 1.2.
If we decide to rename the project after 1.2, I will submit separate PR to make changes in the docs.

WDYT @gaocegege @johnugeorge ?

andreyvelich · 2020-10-28T21:07:52Z

Preview: https://deploy-preview-2312--competent-brattain-de2d6d.netlify.app/.

I have updated doc with v1alpha3 reference.

/cc @RFMVasconcelos @gaocegege @johnugeorge

rui-vas

Looking great!

You are indeed writing to the right branch! What we need to do is create the v1.1 branch and update master to be v1.2.

Let me create an issue about it :)

rui-vas · 2020-10-30T09:50:57Z

Oh, it looks like there is one already -> #2322

andreyvelich · 2020-10-30T14:46:27Z

Thanks @RFMVasconcelos.
Do you have any comments/objections on the doc changes in this PR?

andreyvelich · 2020-11-02T16:55:50Z

@RFMVasconcelos @8bitmp3 @gaocegege @johnugeorge I removed WIP status, since kubeflow/manifests#1593 is ready to merge. If you have any objections and comments on this PR, please let me know.
If not, we can merge it and start work on other Katib documentation PRs

8bitmp3

@andreyvelich Thanks for the PR!

I've added a few suggestions and comments. Feel free to disregard them 👍

Maybe in the Katib explanation in /components/katib/overview.md we could also add a small link for all the new ML users about AutoML (e.g. https://www.fast.ai/2018/07/16/auto-ml2/) and/or Microsoft Azure, Google Cloud and AWS AutoML solution docs?

Thank you for your help!

Update: also maybe we should move the "about" section up in overview.md such that:

Katib is a Kubernetes-native project for automated machine learning (AutoML) —
it's a system for hyperparameter tuning and neural architecture search. 
Katib supports a number of machine learning frameworks, including
TensorFlow, MXNet, PyTorch, XGBoost, and others.
The [Katib project](https://github.com/kubeflow/katib) is open source.
The [developer guide](https://github.com/kubeflow/katib/blob/master/docs/developer-guide.md)
is a good starting point for developers who want to contribute to the project.

8bitmp3 · 2020-11-02T21:01:38Z

content/en/docs/components/katib/katib-config.md

+This page describes information about
+[Katib config](https://github.com/kubeflow/katib/blob/master/manifests/v1beta1/katib-controller/katib-config.yaml).
+
+Katib config is the Kubernetes
+[Config Map](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) that contains information about:


Thank you for the PR @andreyvelich

Hi, what do you think of this suggestion?

"refactor" to 'This page describes Katib config — the Kubernetes Config Map that contains information about:'

Suggested change

This page describes information about

[Katib config](https://github.com/kubeflow/katib/blob/master/manifests/v1beta1/katib-controller/katib-config.yaml).

Katib config is the Kubernetes

[Config Map](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) that contains information about:

This page describes

[Katib config](https://github.com/kubeflow/katib/blob/master/manifests/v1beta1/katib-controller/katib-config.yaml) —

the Kubernetes

[Config Map](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) that contains information about:

Agree, changed.

8bitmp3 · 2020-11-02T21:04:47Z

content/en/docs/components/katib/katib-config.md

+
+You can edit this Config Map even after deploying Katib.
+
+If you deploy Katib in Kubeflow namespace, to edit Katib config run this:


Maybe just change the order here, use a different (present continuous) tense, and "the" (the definite article) (I checked with the K8s guide, as I'm not 100% sure about these):

Suggested change

If you deploy Katib in Kubeflow namespace, to edit Katib config run this:

If you are deploying Katib in the Kubeflow namespace, run this command to edit your Katib config:

Agree, changed.

8bitmp3 · 2020-11-02T21:10:47Z

content/en/docs/components/katib/katib-config.md

+
+`kubectl edit configMap katib-config -n kubeflow`
+


Suggestion - use code style/code font/code block/codefence (K8s style guide, Google style guide:

Suggested change

`kubectl edit configMap katib-config -n kubeflow`

```shell

kubectl edit configMap katib-config -n kubeflow

```

(without the tabs that indent the code block - they render differently if I remove them)

@8bitmp3 Should we use ```shell everywhere?
e.g. https://github.com/kubeflow/website/blame/master/content/en/docs/components/hyperparameter-tuning/hyperparameter.md#L144 ?

@8bitmp3 I've just seen you comment: https://github.com/kubeflow/website/pull/2320/files#r516300401 about it.
Will do the change in this PR.

Done in fe91e74.

content/en/docs/components/katib/katib-config.md

8bitmp3 · 2020-11-02T21:11:47Z

content/en/docs/components/katib/katib-config.md

+
+All of these settings except **`image`** can be omitted. If you don't specify any other settings, default value is set.
+
+1. `image` - Docker image for the `File` metrics collector's container.


Suggested change

1. `image` - Docker image for the `File` metrics collector's container.

1. `image` - a Docker image for the `File` metrics collector's container.

Agree, changed.
@8bitmp3 I made all list items with not capital letter to be consistent (e.g. https://github.com/kubeflow/website/blame/62aba5ce7a065eb2b60d6b7884f4ab075be33fcc/content/en/docs/components/katib/katib-config.md#L66)
WDYT ?

content/en/docs/components/katib/katib-config.md

content/en/docs/components/katib/overview.md

content/en/docs/components/katib/katib-config.md

8bitmp3 · 2020-11-02T21:42:46Z

content/en/docs/components/katib/overview.md

+Katib is Kubernetes-native project for automated machine learning (AutoML).
+Use Katib for automated tuning of your machine learning (ML) model's hyperparameters and architecture.


Suggestions:

I think lines 87-95 about "the Katib project" should be right in the beginning of overview.md:

Suggested change

Katib is Kubernetes-native project for automated machine learning (AutoML).

Use Katib for automated tuning of your machine learning (ML) model's hyperparameters and architecture.

Katib is a Kubernetes-native project for automated machine learning (AutoML) —

it's a system for hyperparameter tuning and neural architecture search.

Katib supports a number of machine learning frameworks, including

TensorFlow, MXNet, PyTorch, XGBoost, and others.

The [Katib project](https://github.com/kubeflow/katib) is open source.

The [developer guide](https://github.com/kubeflow/katib/blob/master/docs/developer-guide.md)

is a good starting point for developers who want to contribute to the project.

content/en/docs/components/katib/overview.md

andreyvelich · 2020-11-10T18:45:23Z

Thank you for the another review @8bitmp3 !
I've addressed your comments.
Preview: https://deploy-preview-2312--competent-brattain-de2d6d.netlify.app/.

8bitmp3 · 2020-11-10T20:25:57Z

@andreyvelich Thanks. If you're OK with the suggestions/own changes, feel free to get the LGTM and approve labels from the AutoML/Katib experts (which I am not 😄)

/assign @animeshsingh @Bobgy @joeliedtke
(approvers)

andreyvelich · 2020-11-10T21:31:07Z

@8bitmp3 Thank you again for the help on this PR!
If you don't have any other suggestions on the trial-template doc, I'll remove /hold label and we can merge this PR.

/cc @gaocegege @johnugeorge

8bitmp3 · 2020-11-10T23:15:54Z