Add api doc #303

YujiOshima · 2018-12-19T15:17:41Z

Fix #150
We can gen doc by pkg/api/build.sh script from api.proto.
I didn't use Kubernetes doc generater https://kubernetes.io/docs/contribute/generate-ref-docs/kubernetes-api/
It may be better to use it in the future.

Signed-off-by: YujiOshima yuji.oshima0x3fd@gmail.com

This change is

Signed-off-by: YujiOshima <yuji.oshima0x3fd@gmail.com>

YujiOshima · 2018-12-19T15:17:56Z

/assign @jlewi @richardsliu

johnugeorge · 2018-12-19T19:20:29Z

pkg/api/api.swagger.json

@@ -347,6 +356,7 @@
    },
    "/api/Manager/GetWorkerFullInfo": {
      "get": {
+        "summary": "* \nGet a full informations related to specified Workers.\nIt includes Worker Config, HyperParameters and Metrics Logs.",


a full informations -> full information

johnugeorge · 2018-12-19T19:21:21Z

pkg/api/api.swagger.json

@@ -390,6 +400,7 @@
    },
    "/api/Manager/GetWorkers": {
      "get": {
+        "summary": "* \nGet a Worker Configs and Statuses from DB by ID of Study, Trial or Worker.",


configs and status of a worker

johnugeorge · 2018-12-19T19:26:50Z

pkg/api/python/api_pb2_grpc.py

-    pass
+    """*
+    Create or Update parameter set for a suggestion service.
+    When you specified a ID of parameter set, it will update the parameter set by your request.


When you specified ->if you specify

hougangliu

Reviewable status: 0 of 10 files reviewed, 16 unresolved discussions (waiting on @johnugeorge, @YujiOshima, @ddysher, and @texasmichelle)

pkg/api/api.proto, line 72 at r1 (raw file):

    };
    /** 
     * Get a Worker Configs and Statuses from DB by ID of Study, Trial or Worker.

s/Statuses/Status

pkg/api/api.proto, line 90 at r1 (raw file):

    /** 
     * Get a full informations related to specified Workers.
     * It includes Worker Config, HyperParameters and Metrics Logs.

s/informations/information

pkg/api/api.proto, line 125 at r1 (raw file):

     * Create or Update parameter set for a suggestion service.
     * When you specified a ID of parameter set, it will update the parameter set by your request.
     * When you specified no ID, it will create a new parameter set for corresponding study and suggestion service.

s/specified/specify
s/a ID/an ID
s/you specified no ID/you don't specify an ID

pkg/api/api.proto, line 308 at r1 (raw file):

/**
 * Parameter for Suggestion service. Key value format.

s/Key value/Key-value

pkg/api/api.proto, line 317 at r1 (raw file):

/**
 * Parameter for EarlyStopping service. Key value format.
 */

s/Key value/Key-value

pkg/api/api.proto, line 324 at r1 (raw file):

/**
 * Tag for each resources.

s/resources/resource

pkg/api/api.proto, line 343 at r1 (raw file):

/**
 * A set of Hyperparameter.
 * In a study, multiple trials are evaluated by worker.

s/worker/workers

pkg/api/api.proto, line 394 at r1 (raw file):

/** 
 * Create a Study from Study Config.
 * Generate a unique ID and store the Study to DB.

s/a unique/an unique

pkg/api/api.proto, line 436 at r1 (raw file):

/**
 * Create a Trial from Trial Config.
 * Generate a unique ID and store the Trial to DB.

s/a unique/an unique

pkg/api/api.proto, line 465 at r1 (raw file):

/**
 * Create a Worker from Worker Config.
 * Generate a unique ID and store the Worker to DB.

s/a unique/an unique

pkg/api/api.proto, line 489 at r1 (raw file):

/** 
 * Get a Worker Configs and Statuses from DB by ID of Study, Trial or Worker.
 */

s/Statuses /Status

pkg/api/api.proto, line 515 at r1 (raw file):

/** 
 * Get a full informations related to specified Workers.

s/informations/information

pkg/api/api.swagger.json, line 441 at r1 (raw file):

      "post": {
        "summary": "*\nCreate a Worker from Worker Config.\nGenerate a unique ID and store the Worker to DB.",
        "operationId": "RegisterWorker",

s/a unique/an unique

jlewi · 2018-12-20T13:34:22Z

Thanks @YujiOshima are instructions for generating the API docs somewhere? If not could we add them?

Signed-off-by: YujiOshima <yuji.oshima0x3fd@gmail.com>

YujiOshima · 2018-12-21T10:16:48Z

@richardsliu @hougangliu Thank you! I updated!
@jlewi I added README https://github.com/kubeflow/katib/blob/c6525022615c7275c6fdac30fda1fc2a87be7944/pkg/api/README.md for API files and docs.

jlewi · 2018-12-21T13:54:48Z

/assign @hougangliu
/unassign @richardsliu (OOO)

LGTM

@hougangliu Could you take another look please and see if you are satisfied? thanks!

hougangliu

Reviewed 1 of 10 files at r1.
Reviewable status: 1 of 11 files reviewed, 19 unresolved discussions (waiting on @johnugeorge, @YujiOshima, @ddysher, and @texasmichelle)

pkg/api/README.md, line 4 at r2 (raw file):

This is APIs for Katib.
Manager service is an API for core component.
Suggestion  service is an API for Suggestion services.

s/Suggestion service/Suggestion service

pkg/api/README.md, line 10 at r2 (raw file):

Please refer to [api.md](./gen-doc/api.md).

## Update API and generatie documents

s/generatie/generate

pkg/api/README.md, line 13 at r2 (raw file):

When you want to edit API, please only edit [api.proto](./api.proto) and generate other files from it.
Documents are also generated from [api.proto](./api.proto) by [protoc-gen-doc](https://github.com/pseudomuto/protoc-gen-doc).
By [build.sh](./build.sh), you can update every files from api.proto and generate docs.

s/files/file

hougangliu · 2018-12-22T14:53:22Z

Thanks @YujiOshima . Lgtm except these typo error.

Signed-off-by: YujiOshima <yuji.oshima0x3fd@gmail.com>

YujiOshima · 2018-12-25T09:05:35Z

@hougangliu Thanks! fixed.

hougangliu · 2018-12-25T10:24:12Z

/lgtm

YujiOshima · 2018-12-25T17:20:16Z

Thanks!
/approve

k8s-ci-robot · 2018-12-25T17:20:22Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: YujiOshima

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~~ [YujiOshima]

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

add api doc

8cc162e

Signed-off-by: YujiOshima <yuji.oshima0x3fd@gmail.com>

k8s-ci-robot requested review from ddysher and texasmichelle December 19, 2018 15:17

k8s-ci-robot added the size/XXL label Dec 19, 2018

k8s-ci-robot assigned jlewi and richardsliu Dec 19, 2018

johnugeorge reviewed Dec 19, 2018

View reviewed changes

hougangliu reviewed Dec 20, 2018

View reviewed changes

YujiOshima added 2 commits December 21, 2018 19:13

fix typo

835e7af

Signed-off-by: YujiOshima <yuji.oshima0x3fd@gmail.com>

add instructions for update api files and docs

c652502

Signed-off-by: YujiOshima <yuji.oshima0x3fd@gmail.com>

k8s-ci-robot assigned hougangliu Dec 21, 2018

hougangliu reviewed Dec 22, 2018

View reviewed changes

fix typo

682520d

Signed-off-by: YujiOshima <yuji.oshima0x3fd@gmail.com>

k8s-ci-robot added the lgtm label Dec 25, 2018

hougangliu mentioned this pull request Dec 25, 2018

add bestTrialId to statusJob status #312

Merged

k8s-ci-robot added the approved label Dec 25, 2018

k8s-ci-robot merged commit f24889c into kubeflow:master Dec 25, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add api doc #303

Add api doc #303

YujiOshima commented Dec 19, 2018 •

edited by jlewi

Loading

YujiOshima commented Dec 19, 2018

johnugeorge Dec 19, 2018

johnugeorge Dec 19, 2018

johnugeorge Dec 19, 2018

hougangliu left a comment

jlewi commented Dec 20, 2018

YujiOshima commented Dec 21, 2018

jlewi commented Dec 21, 2018

hougangliu left a comment

hougangliu commented Dec 22, 2018

YujiOshima commented Dec 25, 2018

hougangliu commented Dec 25, 2018

YujiOshima commented Dec 25, 2018

k8s-ci-robot commented Dec 25, 2018

Add api doc #303

Add api doc #303

Conversation

YujiOshima commented Dec 19, 2018 • edited by jlewi Loading

YujiOshima commented Dec 19, 2018

johnugeorge Dec 19, 2018

Choose a reason for hiding this comment

johnugeorge Dec 19, 2018

Choose a reason for hiding this comment

johnugeorge Dec 19, 2018

Choose a reason for hiding this comment

hougangliu left a comment

Choose a reason for hiding this comment

jlewi commented Dec 20, 2018

YujiOshima commented Dec 21, 2018

jlewi commented Dec 21, 2018

hougangliu left a comment

Choose a reason for hiding this comment

hougangliu commented Dec 22, 2018

YujiOshima commented Dec 25, 2018

hougangliu commented Dec 25, 2018

YujiOshima commented Dec 25, 2018

k8s-ci-robot commented Dec 25, 2018

YujiOshima commented Dec 19, 2018 •

edited by jlewi

Loading