diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 041b02e88d..b11d184b82 100644 --- a/.github/workflows/tests.yml +++ b/.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 diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000000..1b9e1708eb --- /dev/null +++ b/.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 diff --git a/Makefile b/Makefile index 6828360adc..6edbb8304e 100644 --- a/Makefile +++ b/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) + diff --git a/doc-requirements.in b/doc-requirements.in new file mode 100644 index 0000000000..d74ecdb32e --- /dev/null +++ b/doc-requirements.in @@ -0,0 +1,6 @@ +sphinx +sphinx-prompt +sphinx-material +sphinx-code-include +sphinx-autoapi +sphinx-copybutton diff --git a/doc-requirements.txt b/doc-requirements.txt new file mode 100644 index 0000000000..4623f05504 --- /dev/null +++ b/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 diff --git a/rsts/Makefile b/rsts/Makefile new file mode 100644 index 0000000000..d06c8c4804 --- /dev/null +++ b/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) + + + diff --git a/rsts/conf.py b/rsts/conf.py index 4246c287fb..e239fd4568 100644 --- a/rsts/conf.py +++ b/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'), ] diff --git a/rsts/index.rst b/rsts/index.rst index b7524327c6..07089ddae8 100644 --- a/rsts/index.rst +++ b/rsts/index.rst @@ -19,16 +19,15 @@ Welcome to the documentation hub for Flyte. :maxdepth: 1 :name: examplesdoctoc - FlyteSnacks - Examples & Cookbook + Flytekit Python - Learn by Example .. toctree:: :caption: Generated Documentation from Source :maxdepth: 1 :name: sourcecodedocstoc - Flytekit Python + Flytekit Python Flytekit JAVA - flyteidl/index FlytePropeller FlyteAdmin FlytePlugins diff --git a/rsts/user/getting_started/index.rst b/rsts/user/getting_started/index.rst index ef76ac29c9..4d7a7a3bcd 100644 --- a/rsts/user/getting_started/index.rst +++ b/rsts/user/getting_started/index.rst @@ -14,4 +14,4 @@ Getting Started examples create_first - more_examples + Learn Flytekit by example