[doc] API Documentation

[gaocegege]

We need the documentation for v1alpha2 API

[richardsliu]

Definitely need documentation and API reference for v1beta1 and stable release.

[abhi-g]

/priority p1

[netankit]

/priority p1

[jlewi]

Anyone working on this?

Any idea on how we can autogenerate docs? Is that something we can reasonable get done in time for 0.4 or should we punt to 0.5?

/cc @richardsliu

[richardsliu]

We should be close to finishing the v1beta2 APIs for tf-operator. This would be a good opportunity to have API documentation ready.

[richardsliu]

@gaocegege @johnugeorge

Preview version: https://github.com/richardsliu/tf-operator/blob/test_md/tensorflow.md#TFJob

[johnugeorge]

looks good. Is something else pending?

[richardsliu]

I need to check in the tool (requires some configuration changes) and then somehow link the API reference from the kubeflow website. Then probably write the instructions on how to generate this for other operators.

[johnugeorge]

SGTM

[sarahmaddox]

This looks great! Thanks @richardsliu. Some suggestions and questions:

• The generated reference is for version v1beta2, whereas the currently available version is v1beta1. Do you know when we'll be launching v1beta2?

• Currently, the generator pushes the output to a file called tensorflow.md in the kubeflow/tf-operator repo on GitHub. Two comments:

  • The content of the file is HTML, not Markdown, so it'd be better to use the .html extension.
  • Would it be possible to push the output directly to a doc page instead of into the kubeflow/tf-operator repo? For example, can you push the generated output to something like this: https://github.com/kubeflow/website/content/docs/reference/tfjob/v1beta2/tensorflow.html? Of course, you'd also need to change all the internal paths.

• Similar comments for the generated file common.md - can you push the output to something like this: https://github.com/kubeflow/website/content/docs/reference/tfjob/v1beta2/common.html?

• Does the doc generation produce just those two files (tensorflow.md and common.md)? I couldn't see any others in your forked repo, but may have missed some.

• If you can push the generated doc directly to the kubeflow/website directory as suggested above, then I'll add a new reference section to the docs to include the TFJob reference now, and later other references.

• As well as including the generated reference in the new reference section, I'll add a link to it from the existing TFJob guide: https://www.kubeflow.org/docs/components/tftraining/

[richardsliu]

Thanks @sarahmaddox. We are planning to launch the v1beta2 APIs as part of 0.5.0.

So the reason for generating those two .md files in the tf-operator repo is purely out of convenience. The tool that I am using also assumes that you are generating documentation in the same repo.

I can try to generate the same content again but under kubeflow/website. Can you help create the section and navigation buttons?

[sarahmaddox]

Hallo @richardsliu

I've created this PR to show you how it will look:
kubeflow/website#514

The previews of the relevant pages are here:

• https://deploy-preview-514--competent-brattain-de2d6d.netlify.com/docs/reference/
• https://deploy-preview-514--competent-brattain-de2d6d.netlify.com/docs/components/tftraining/#more-information

[richardsliu]

@sarahmaddox I've created a PR for the html files generated. Another reason for using .md is that the formatting works nicely on GitHub. But it should be simple to just add some css to style it up.

[richardsliu]

Examples: https://deploy-preview-516--competent-brattain-de2d6d.netlify.com/docs/references/tfjob/v1beta2/tensorflow/

https://deploy-preview-516--competent-brattain-de2d6d.netlify.com/docs/references/tfjob/v1beta2/common/

[richardsliu]

Latest example: https://deploy-preview-516--competent-brattain-de2d6d.netlify.com/docs/reference/tfjob/v1beta2/tensorflow/
https://deploy-preview-516--competent-brattain-de2d6d.netlify.com/docs/reference/tfjob/v1beta2/common/

[richardsliu]

The documentation is on the kubeflow website now: https://www.kubeflow.org/docs/reference/tfjob/v1beta1/tensorflow/

Keeping this open until the tool/instructions are also merged.

[abhi-g]

Awesome!

…

On Tue, Mar 5, 2019 at 1:40 PM Richard Liu ***@***.***> wrote: The documentation is on the kubeflow website now: https://www.kubeflow.org/docs/reference/tfjob/v1beta1/tensorflow/ Keeping this open until the tool/instructions are also merged. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#731 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ALOqZh78a4-TTDYobwV3zzrstzv-QGjBks5vTuRagaJpZM4VSC2q> .

[johnugeorge]

@richardsliu do we need to keep docs of both versions in the website?

[richardsliu]

We should keep docs for all the versions that we currently support (i.e. v1beta1 and v1beta2).