From ee107e3e8600c49717145ae461625876a9ff154c Mon Sep 17 00:00:00 2001 From: Ketan Umare Date: Thu, 28 Jan 2021 10:18:08 -0800 Subject: [PATCH 1/3] Enabling RTD supported format for docs --- rsts/Makefile | 20 ++++++ rsts/conf.py | 37 ++++++++-- rsts/index.rst | 5 +- rsts/make.bat | 36 ++++++++++ rsts/requirements.in | 6 ++ rsts/requirements.txt | 105 ++++++++++++++++++++++++++++ rsts/user/getting_started/index.rst | 2 +- 7 files changed, 200 insertions(+), 11 deletions(-) create mode 100644 rsts/Makefile create mode 100644 rsts/make.bat create mode 100644 rsts/requirements.in create mode 100644 rsts/requirements.txt diff --git a/rsts/Makefile b/rsts/Makefile new file mode 100644 index 0000000000..a761edf1c9 --- /dev/null +++ b/rsts/Makefile @@ -0,0 +1,20 @@ +# 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..6aad5452a8 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 = ['_static'] +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..aa72ba436e 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/make.bat b/rsts/make.bat new file mode 100644 index 0000000000..47d656bb74 --- /dev/null +++ b/rsts/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build +set SPHINXPROJ=simpleble + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/rsts/requirements.in b/rsts/requirements.in new file mode 100644 index 0000000000..d74ecdb32e --- /dev/null +++ b/rsts/requirements.in @@ -0,0 +1,6 @@ +sphinx +sphinx-prompt +sphinx-material +sphinx-code-include +sphinx-autoapi +sphinx-copybutton diff --git a/rsts/requirements.txt b/rsts/requirements.txt new file mode 100644 index 0000000000..529c8bc184 --- /dev/null +++ b/rsts/requirements.txt @@ -0,0 +1,105 @@ +# +# This file is autogenerated by pip-compile +# To update, run: +# +# make requirements.txt +# +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 requirements.in +sphinx-code-include==1.1.1 + # via -r requirements.in +sphinx-copybutton==0.3.1 + # via -r requirements.in +sphinx-material==0.0.32 + # via -r requirements.in +sphinx-prompt==1.3.0 + # via -r requirements.in +sphinx==3.4.3 + # via + # -r 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/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 From 67089bc66afdd9f7908cfa2ff902e834d80590ec Mon Sep 17 00:00:00 2001 From: Ketan Umare Date: Thu, 28 Jan 2021 11:10:59 -0800 Subject: [PATCH 2/3] Updated Docs requirements --- .github/workflows/tests.yml | 8 ----- .readthedocs.yml | 16 +++++++++ Makefile | 13 +++++++ rsts/requirements.in => doc-requirements.in | 0 rsts/requirements.txt => doc-requirements.txt | 14 ++++---- rsts/Makefile | 3 ++ rsts/conf.py | 2 +- rsts/make.bat | 36 ------------------- 8 files changed, 40 insertions(+), 52 deletions(-) create mode 100644 .readthedocs.yml rename rsts/requirements.in => doc-requirements.in (100%) rename rsts/requirements.txt => doc-requirements.txt (89%) delete mode 100644 rsts/make.bat 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/rsts/requirements.in b/doc-requirements.in similarity index 100% rename from rsts/requirements.in rename to doc-requirements.in diff --git a/rsts/requirements.txt b/doc-requirements.txt similarity index 89% rename from rsts/requirements.txt rename to doc-requirements.txt index 529c8bc184..4623f05504 100644 --- a/rsts/requirements.txt +++ b/doc-requirements.txt @@ -2,7 +2,7 @@ # This file is autogenerated by pip-compile # To update, run: # -# make requirements.txt +# pip-compile doc-requirements.in # alabaster==0.7.12 # via sphinx @@ -61,18 +61,18 @@ snowballstemmer==2.1.0 soupsieve==2.1 # via beautifulsoup4 sphinx-autoapi==1.6.0 - # via -r requirements.in + # via -r doc-requirements.in sphinx-code-include==1.1.1 - # via -r requirements.in + # via -r doc-requirements.in sphinx-copybutton==0.3.1 - # via -r requirements.in + # via -r doc-requirements.in sphinx-material==0.0.32 - # via -r requirements.in + # via -r doc-requirements.in sphinx-prompt==1.3.0 - # via -r requirements.in + # via -r doc-requirements.in sphinx==3.4.3 # via - # -r requirements.in + # -r doc-requirements.in # sphinx-autoapi # sphinx-code-include # sphinx-copybutton diff --git a/rsts/Makefile b/rsts/Makefile index a761edf1c9..d06c8c4804 100644 --- a/rsts/Makefile +++ b/rsts/Makefile @@ -18,3 +18,6 @@ help: # "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 6aad5452a8..e239fd4568 100644 --- a/rsts/conf.py +++ b/rsts/conf.py @@ -98,7 +98,7 @@ # a list of builtin themes. # html_logo = "flyte_lockup_on_dark.png" -html_static_path = ['_static'] +html_static_path = [] html_theme = "sphinx_material" html_theme_options = { # Set the name of the project to appear in the navigation. diff --git a/rsts/make.bat b/rsts/make.bat deleted file mode 100644 index 47d656bb74..0000000000 --- a/rsts/make.bat +++ /dev/null @@ -1,36 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build -set SPHINXPROJ=simpleble - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% - -:end -popd From e88f787202fba6ce9dc869f4ac38b94f41aff0eb Mon Sep 17 00:00:00 2001 From: Ketan Umare Date: Thu, 28 Jan 2021 11:24:18 -0800 Subject: [PATCH 3/3] Index updated --- rsts/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rsts/index.rst b/rsts/index.rst index aa72ba436e..07089ddae8 100644 --- a/rsts/index.rst +++ b/rsts/index.rst @@ -26,7 +26,7 @@ Welcome to the documentation hub for Flyte. :maxdepth: 1 :name: sourcecodedocstoc - Flytekit Python + Flytekit Python Flytekit JAVA FlytePropeller FlyteAdmin