kubeflow / metadata

Repository for assets related to Metadata.
Apache License 2.0
121 stars 69 forks source link

Add sphinx docs for Python SDK. #168

Closed zhenghuiwang closed 4 years ago

zhenghuiwang commented 4 years ago

Related to https://github.com/kubeflow/website/issues/1206

This PR aims to check in the configuration to auto generate python docs from python docstrings, using readthedocs.io

The improvement of the actual doc content should be done in subsequent PR on docstrings.

Preview: https://kf-metadata-pr-168.readthedocs.io/en/latest/index.html


This change is Reviewable

zhenghuiwang commented 4 years ago

/assign @sarahmaddox

jinchihe commented 4 years ago

Hello @zhenghuiwang that's really great to generate docs for SDK, I just done that for kubeflow fairing, may I suggest to update to sphinx_rtd_theme style that seems bette, and shall we add content in the index page so that user can click and read that directly as below link: https://kubeflow-fairing.readthedocs.io/en/latest/index.html

But that's only suggestion, nice to have. That's good for current behavior...haha

zhenghuiwang commented 4 years ago

@jinchihe Thanks for the suggestions! I change the theme and it looks much better.

Fairing has many submodules and TOC helps to navigate among them. This sdk has a single module with a bunch of classes. I don't find a good sphinx plugin to automatically generate the TOC for these classes. I will leave the navigation to the Index page or search.

jinchihe commented 4 years ago

Sounds great! /lgtm

sarahmaddox commented 4 years ago

Thanks @zhenghuiwang! When the SDK docs are available on readthedocs.io, we can add a link to them from the Kubeflow website. I'll add a comment to the issue.

/lgtm

zhenghuiwang commented 4 years ago

/approve

k8s-ci-robot commented 4 years ago

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: zhenghuiwang

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](https://github.com/kubeflow/metadata/blob/master/OWNERS)~~ [zhenghuiwang] Approvers can indicate their approval by writing `/approve` in a comment Approvers can cancel approval by writing `/approve cancel` in a comment