Enabling RTD supported format for docs (#680)

.github/workflows/tests.yml

@@ -22,11 +22,3 @@ jobs:
         echo "current-context:" $(kubectl config current-context)
         echo "environment-kubeconfig:" ${KUBECONFIG}
         make end2end_execute
-  docs:
-    runs-on: ubuntu-latest
-    strategy:
-      max-parallel: 1
-    steps:
-    - uses: actions/checkout@v1
-    - name: Build docs
-      run: make generate-docs

.readthedocs.yml

@@ -0,0 +1,16 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: rsts/conf.py
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.8
+  install:
+    - requirements: doc-requirements.txt

Makefile

@@ -1,3 +1,7 @@
+define PIP_COMPILE
+pip-compile $(1) --upgrade --verbose
+endef
+
 .PHONY: kustomize
 kustomize:
 	KUSTOMIZE_VERSION=3.8.4 bash script/generate_kustomize.sh
@@ -30,3 +34,12 @@ generate-docs: generate-dependent-repo-docs
 .PHONY: generate-dependent-repo-docs
 generate-dependent-repo-docs:
 	@FLYTEKIT_VERSION=0.15.4 FLYTEIDL_VERSION=0.18.11 ./script/update_ref_docs.sh
+
+.PHONY: install-piptools
+install-piptools:
+	pip install -U pip-tools
+
+.PHONY: doc-requirements.txt
+doc-requirements.txt: doc-requirements.in install-piptools
+	$(call PIP_COMPILE,doc-requirements.in)
+

doc-requirements.in

@@ -0,0 +1,6 @@
+sphinx
+sphinx-prompt
+sphinx-material
+sphinx-code-include
+sphinx-autoapi
+sphinx-copybutton

doc-requirements.txt

@@ -0,0 +1,105 @@
+#
+# This file is autogenerated by pip-compile
+# To update, run:
+#
+#    pip-compile doc-requirements.in
+#
+alabaster==0.7.12
+    # via sphinx
+astroid==2.4.2
+    # via sphinx-autoapi
+babel==2.9.0
+    # via sphinx
+beautifulsoup4==4.9.3
+    # via
+    #   sphinx-code-include
+    #   sphinx-material
+certifi==2020.12.5
+    # via requests
+chardet==4.0.0
+    # via requests
+css-html-js-minify==2.5.5
+    # via sphinx-material
+docutils==0.16
+    # via sphinx
+idna==2.10
+    # via requests
+imagesize==1.2.0
+    # via sphinx
+jinja2==2.11.2
+    # via
+    #   sphinx
+    #   sphinx-autoapi
+lazy-object-proxy==1.4.3
+    # via astroid
+lxml==4.6.2
+    # via sphinx-material
+markupsafe==1.1.1
+    # via jinja2
+packaging==20.8
+    # via sphinx
+pygments==2.7.4
+    # via
+    #   sphinx
+    #   sphinx-prompt
+pyparsing==2.4.7
+    # via packaging
+python-slugify[unidecode]==4.0.1
+    # via sphinx-material
+pytz==2020.5
+    # via babel
+pyyaml==5.4.1
+    # via sphinx-autoapi
+requests==2.25.1
+    # via sphinx
+six==1.15.0
+    # via
+    #   astroid
+    #   sphinx-code-include
+snowballstemmer==2.1.0
+    # via sphinx
+soupsieve==2.1
+    # via beautifulsoup4
+sphinx-autoapi==1.6.0
+    # via -r doc-requirements.in
+sphinx-code-include==1.1.1
+    # via -r doc-requirements.in
+sphinx-copybutton==0.3.1
+    # via -r doc-requirements.in
+sphinx-material==0.0.32
+    # via -r doc-requirements.in
+sphinx-prompt==1.3.0
+    # via -r doc-requirements.in
+sphinx==3.4.3
+    # via
+    #   -r doc-requirements.in
+    #   sphinx-autoapi
+    #   sphinx-code-include
+    #   sphinx-copybutton
+    #   sphinx-material
+    #   sphinx-prompt
+sphinxcontrib-applehelp==1.0.2
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==1.0.3
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.3
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.4
+    # via sphinx
+text-unidecode==1.3
+    # via python-slugify
+unidecode==1.1.2
+    # via
+    #   python-slugify
+    #   sphinx-autoapi
+urllib3==1.26.3
+    # via requests
+wrapt==1.12.1
+    # via astroid
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools

rsts/Makefile

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = flyte
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+
+

rsts/conf.py

@@ -15,7 +15,6 @@
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
-import sphinx_rtd_theme
 
 # -- Project information -----------------------------------------------------
 
@@ -48,6 +47,12 @@
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'sphinx.ext.extlinks',
+    "sphinx.ext.napoleon",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.coverage",
+    "sphinx-prompt",
+    "sphinx_copybutton",
 ]
 
 extlinks = {
@@ -92,14 +97,32 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
-html_static_path = ['_static']
 html_logo = "flyte_lockup_on_dark.png"
+html_static_path = []
+html_theme = "sphinx_material"
 html_theme_options = {
-    'logo_only': True,
-    'display_version': False,
+    # Set the name of the project to appear in the navigation.
+    "nav_title": "Flyte",
+    # Set you GA account ID to enable tracking
+    "google_analytics_account": "G-YQL24L5CKY",
+    # Specify a base_url used to generate sitemap.xml. If not
+    # specified, then no sitemap will be built.
+    "base_url": "https://github.com/lyft/flyte",
+    # Set the color and the accent color
+    "color_primary": "deep-purple",
+    "color_accent": "blue",
+    # Set the repo location to get a badge with stats
+    "repo_url": "https://github.com/lyft/flyte/",
+    "repo_name": "flyte",
+    # Visible levels of the global TOC; -1 means unlimited
+    "globaltoc_depth": 1,
+    # If False, expand all TOC entries
+    "globaltoc_collapse": False,
+    # If True, show hidden TOC entries
+    "globaltoc_includehidden": False,
 }
 
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
@@ -119,7 +142,7 @@
 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
 # 'searchbox.html']``.
 #
-# html_sidebars = {}
+html_sidebars = {"**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]}
 
 
 # -- Options for HTMLHelp output ---------------------------------------------
@@ -174,7 +197,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
     (master_doc, 'Flyte', u'Flyte Documentation',
-     author, 'Flyte', 'One line description of project.',
+     author, 'Flyte', 'Accelerate your ML and data workflows to production.',
      'Miscellaneous'),
 ]
 

rsts/index.rst

@@ -19,16 +19,15 @@ Welcome to the documentation hub for Flyte.
    :maxdepth: 1
    :name: examplesdoctoc
 
-   FlyteSnacks - Examples & Cookbook <https://github.com/lyft/flytesnacks/blob/master/README.md>
+   Flytekit Python - Learn by Example <https://flytecookbook.readthedocs.io/en/latest/>
 
 .. toctree::
    :caption: Generated Documentation from Source
    :maxdepth: 1
    :name: sourcecodedocstoc
 
-   Flytekit Python<flytekit/index>
+   Flytekit Python <https://flyte.readthedocs.io/projects/flytekit/en/master/>
    Flytekit JAVA  <https://github.com/spotify/flytekit-java>
-   flyteidl/index
    FlytePropeller <https://pkg.go.dev/mod/github.com/lyft/flytepropeller>
    FlyteAdmin <https://pkg.go.dev/mod/github.com/lyft/flyteadmin>
    FlytePlugins <https://pkg.go.dev/mod/github.com/lyft/flyteplugins>

rsts/user/getting_started/index.rst

@@ -14,4 +14,4 @@ Getting Started
 
    examples
    create_first
-   more_examples 
+   Learn Flytekit by example <https://flytecookbook.readthedocs.io/en/latest/>