chore: Clean up KFP SDK docstrings, make formatting a little more con…

…sistent (kubeflow#4218) * Prepare SDK docs environment so its easier to understand how to build the docs locally so theyre consistent with ReadTheDocs. * Clean up docstrings for kfp.Client * Add in updates to the docs for compiler and components * Update components area to add in code references and make formatting a little more consistent. * Clean up containers, add in custom CSS to ensure we do not overflow on inline code blocks * Clean up containers, add in custom CSS to ensure we do not overflow on inline code blocks * Remove unused kfp.notebook package links * Clean up a few more errant references * Clean up the DSL docs some more * Update SDK docs for KFP extensions to follow Sphinx guidelines * Clean up formatting of docstrings after Ark-Kuns comments
chensun · Aug 7, 2020 · e968c95 · e968c95
1 parent dbc9d56
commit e968c95
Show file tree

Hide file tree

Showing 32 changed files with 683 additions and 617 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,8 @@
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+version: 2
+sphinx:
+  configuration: docs/conf.py
+python:
+  version: 3.7
+  install:
+    - requirements: sdk/python/requirements.txt
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -0,0 +1,3 @@
+.rst-content code, .rst-content tt, code {
+    white-space: normal;
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -55,7 +55,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Kubeflow Pipelines'
-copyright = '2019, Google'
+copyright = '2020, Google'
 author = 'Google'
 
 # The short X.Y version
@@ -106,7 +106,6 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
 
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -140,6 +139,10 @@
 #
 # html_sidebars = {}
 
+html_css_files = [
+    'custom.css',
+]
+
 
 # -- Options for HTMLHelp output ---------------------------------------------
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -3,20 +3,20 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Kubeflow Pipelines SDK API reference
-================================================
+Kubeflow Pipelines SDK API
+==========================
 
 Main documentation: https://www.kubeflow.org/docs/pipelines/
 
 Source code: https://github.com/kubeflow/pipelines/
 
 .. toctree::
    :maxdepth: 3
-   :caption: Contents:
+   :caption: Contents
 
+   self
    source/kfp
 
-
 .. * :ref:`modindex`
 .. * :ref:`kfp-ref`
 .. * :ref:`search`

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,2 @@
+sphinx==3.1.2
+sphinx_rtd_theme==0.5.0
diff --git a/docs/source/kfp.client.rst b/docs/source/kfp.client.rst
@@ -1,13 +1,13 @@
 kfp.Client class
-------------------
+================
 
 .. autoclass:: kfp.Client
     :members:
     :undoc-members:
     :show-inheritance:
 
 Generated APIs
-------------------
+--------------
 
 .. toctree::
     :maxdepth: 2

diff --git a/docs/source/kfp.components.structures.rst b/docs/source/kfp.components.structures.rst
@@ -9,5 +9,6 @@ kfp.components.structures package
     :imported-members:
 
 .. toctree::
+    :maxdepth: 2
 
     kfp.components.structures.kubernetes
diff --git a/docs/source/kfp.notebook.rst b/docs/source/kfp.notebook.rst
diff --git a/docs/source/kfp.rst b/docs/source/kfp.rst
@@ -7,12 +7,11 @@ kfp package
 .. toctree::
     :maxdepth: 2
 
+    kfp.client
     kfp.compiler
     kfp.components
     kfp.containers
     kfp.dsl
-    kfp.client
-    kfp.notebook
     kfp.extensions
 
 .. automodule:: kfp

diff --git a/docs/source/modules.rst b/docs/source/modules.rst