Monodocs sphinx build (#4347)

* rename rsts to docs Signed-off-by: Niels Bantilan <[email protected]> * update docs reqs Signed-off-by: Niels Bantilan <[email protected]> * update reqs, styles Signed-off-by: Niels Bantilan <[email protected]> * update doc requirements Signed-off-by: Niels Bantilan <[email protected]> * edit gitignore Signed-off-by: Niels Bantilan <[email protected]> * update doc requirement Signed-off-by: Niels Bantilan <[email protected]> * update doc requirements Signed-off-by: Niels Bantilan <[email protected]> * update doc requirements Signed-off-by: Niels Bantilan <[email protected]> * minor clean up Signed-off-by: Niels Bantilan <[email protected]> * update deps Signed-off-by: Niels Bantilan <[email protected]> * use doc-requirements.in in .readthedocs.yml Signed-off-by: Niels Bantilan <[email protected]> * updates Signed-off-by: Niels Bantilan <[email protected]> * check in new docs Signed-off-by: Niels Bantilan <[email protected]> * clean up most reference warnings Signed-off-by: Niels Bantilan <[email protected]> * fix ref links Signed-off-by: Niels Bantilan <[email protected]> * update auto examples Signed-off-by: Niels Bantilan <[email protected]> * add logic to find/replace invalid links Signed-off-by: Niels Bantilan <[email protected]> * update docs with changes Signed-off-by: Niels Bantilan <[email protected]> * clean up toc list for deployment docs Signed-off-by: Niels Bantilan <[email protected]> * add back rsts Signed-off-by: Niels Bantilan <[email protected]> * add readthedocs config for monodocs Signed-off-by: Niels Bantilan <[email protected]> * incorporate changes from master Signed-off-by: Niels Bantilan <[email protected]> * reformat concepts section Signed-off-by: Niels Bantilan <[email protected]> * move monodocs readthedocs config Signed-off-by: Niels Bantilan <[email protected]> * debug readthedocs config Signed-off-by: Niels Bantilan <[email protected]> * add monodocs requirements Signed-off-by: Niels Bantilan <[email protected]> * update reqs Signed-off-by: Niels Bantilan <[email protected]> * fix furo dep Signed-off-by: Niels Bantilan <[email protected]> * update logo Signed-off-by: Niels Bantilan <[email protected]> * update logo Signed-off-by: Niels Bantilan <[email protected]> * update css Signed-off-by: Niels Bantilan <[email protected]> * update css Signed-off-by: Niels Bantilan <[email protected]> * update sidebar caption styling Signed-off-by: Niels Bantilan <[email protected]> * update sidebar css * use conda to install monodocs deps Signed-off-by: cosmicBboy <[email protected]> * update conda deps Signed-off-by: cosmicBboy <[email protected]> * update makefile docs target Signed-off-by: cosmicBboy <[email protected]> * add furo dep to environment.yaml Signed-off-by: cosmicBboy <[email protected]> * add retry dep Signed-off-by: cosmicBboy <[email protected]> * update vaex deps Signed-off-by: cosmicBboy <[email protected]> * add graphviz to ci Signed-off-by: cosmicBboy <[email protected]> * add graphviz to readthedocs config Signed-off-by: cosmicBboy <[email protected]> * support pointing to local flytekit, flytesnacks, flytectl - add graphviz as conda dependency - remove monodocs-requirements.{in,txt} Signed-off-by: Niels Bantilan <[email protected]> * delete doc-requirements.txt - defer cleaning this up to followup PR Signed-off-by: Niels Bantilan <[email protected]> * revert doc-requirements.txt Signed-off-by: Niels Bantilan <[email protected]> --------- Signed-off-by: Niels Bantilan <[email protected]> Signed-off-by: cosmicBboy <[email protected]> Co-authored-by: Samhita Alla <[email protected]>
flyteorg · Dec 6, 2023 · aff1150 · aff1150
1 parent 76114aa
commit aff1150
Show file tree

Hide file tree

Showing 107 changed files with 29,989 additions and 172 deletions.
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -28,16 +28,26 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Fetch the code
-        uses: actions/checkout@v2
-      - name: Set up Python 3.8
-        uses: actions/setup-python@v2
+        uses: actions/checkout@v4
+      - uses: conda-incubator/setup-miniconda@v3
         with:
-          python-version: "3.8"
-      - name: Install dependencies
+          python-version: 3.9
+          mamba-version: "*"
+          channels: conda-forge
+          channel-priority: true
+          activate-environment: monodocs-env
+          environment-file: monodocs-environment.yaml
+      - shell: bash -el {0}
         run: |
-          python -m pip install --upgrade pip
-          if [ -f doc-requirements.txt ]; then pip install -r doc-requirements.txt; fi
+          conda info
+          conda list
+          conda config --show-sources
+          conda config --show
+          printenv | sort
+      - name: Setup Graphviz
+        uses: ts-graphviz/setup-graphviz@v1
       - name: Build the documentation
+        shell: bash -el {0}
         run: make docs
 
   generate_kustomize:

diff --git a/.gitignore b/.gitignore
@@ -10,10 +10,6 @@ _repos/
 _rsts/
 rsts_tmp/
 .doctrees/
-docs/_sources/
-docs/flytekit/flytekit.interfaces.html
-docs/searchindex.js
-docs/
 !flyteidl/protos/docs
 release/
 __pycache__/
@@ -33,5 +29,14 @@ dist
 *.db
 vendor/
 /docker/sandbox-bundled/images/tar
-rsts/_tags/
-**/bin/
+**/bin/
+docs/_tags/
+docs/flytectl
+docs/protos
+docs/flytekit
+docs/flytesnacks
+docs/examples
+docs/_src
+docs/_projects
+docs/api
+docs/tests
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -16,4 +16,4 @@ sphinx:
 # Optionally set the version of Python and requirements required to build your docs
 python:
   install:
-    - requirements: doc-requirements.txt
+    - requirements: doc-requirements.in
diff --git a/CHANGELOG/CHANGELOG-v0.13.0.md b/CHANGELOG/CHANGELOG-v0.13.0.md
@@ -2,8 +2,8 @@
 
 ## Platform
 - Oauth2 support with SingleSignOn and configuration examples for popular IDP's now available in Flyte.
-  Please see the updated [information and description of the feature](https://github.com/flyteorg/flyte/blob/master/rsts/howto/authentication/index.rst), and the [setup information](https://github.com/flyteorg/flyte/blob/master/rsts/howto/authentication/setup.rst)
-  **Attention: If using Auth already - this is a BREAKING change**. refer to the [migration guide](https://github.com/flyteorg/flyte/blob/master/rsts/howto/authentication/migration.rst) to update configuration to ensure Admin continues to work. (No migration needed if auth is not turned on.)
+  Please see the updated [information and description of the feature](https://github.com/flyteorg/flyte/blob/master/docs/howto/authentication/index.rst), and the [setup information](https://github.com/flyteorg/flyte/blob/master/docs/howto/authentication/setup.rst)
+  **Attention: If using Auth already - this is a BREAKING change**. refer to the [migration guide](https://github.com/flyteorg/flyte/blob/master/docs/howto/authentication/migration.rst) to update configuration to ensure Admin continues to work. (No migration needed if auth is not turned on.)
 
 * Backend improvements to support dynamic workflow visualization (in future releases).
 * Lot of features added to [flytectl](https://flytectl.readthedocs.io/en/latest/) .

diff --git a/CHANGELOG/CHANGELOG-v1.3.0-b5.md b/CHANGELOG/CHANGELOG-v1.3.0-b5.md
@@ -99,7 +99,7 @@ flytectl demo start --image ghcr.io/flyteorg/flyte-sandbox-bundled:sha-e240038be
    ```
 
 ### Databricks Code
-You'll need to upload an [entrypoint](https://gist.github.com/pingsutw/482e7f0134414dac437500344bac5134) file to your dbfs (or S3). This is the referenced gist from the primary [Databricks plugin documentation](https://github.com/flyteorg/flyte/blob/master/rsts/deployment/plugin_setup/webapi/databricks.rst) as well, which currently only covers the `flyte-core` Helm chart installation.
+You'll need to upload an [entrypoint](https://gist.github.com/pingsutw/482e7f0134414dac437500344bac5134) file to your dbfs (or S3). This is the referenced gist from the primary [Databricks plugin documentation](https://github.com/flyteorg/flyte/blob/master/docs/deployment/plugin_setup/webapi/databricks.rst) as well, which currently only covers the `flyte-core` Helm chart installation.
 
 
 ### User Code

diff --git a/Makefile b/Makefile
@@ -3,7 +3,7 @@ include boilerplate/flyte/end2end/Makefile
 include boilerplate/flyte/golang_test_targets/Makefile
 
 define PIP_COMPILE
-pip-compile $(1) --upgrade --verbose --resolver=backtracking
+pip-compile $(1) --upgrade --verbose --resolver=backtracking --annotation-style=line
 endef
 
 GIT_VERSION := $(shell git describe --always --tags)
@@ -81,7 +81,7 @@ helm_upgrade: ## Upgrade helm charts
 
 .PHONY: docs
 docs:
-	make -C rsts clean html SPHINXOPTS=-W
+	make -C docs clean html SPHINXOPTS=-W
 
 .PHONY: help
 help: SHELL := /bin/sh

diff --git a/RELEASE.md b/RELEASE.md
@@ -7,7 +7,7 @@
 1. Open [issues](https://github.com/flyteorg/flyte/issues) and filter by milestone and make sure they are either closed or moved over to the next milestone.
 ## Start a release PR
 1. Run [Generate Flyte Manifests workflow](https://github.com/flyteorg/flyte/actions/workflows/generate_flyte_manifest.yml). It’ll create a PR ([example](https://github.com/flyteorg/flyte/pull/888))
-1. Update [docs version](https://github.com/flyteorg/flyte/blob/master/rsts/conf.py#L33) to match the milestone version.
+1. Update [docs version](https://github.com/flyteorg/flyte/blob/master/docs/conf.py#L33) to match the milestone version.
 1. Create a CHANGELOG file ([example](https://github.com/flyteorg/flyte/pull/888/files#diff-0c33dda4ecbd7e1116ddce683b5e143d85b22e43223ca258ecc571fb3b240a57))
 1. Wait for endtoend tests to finish then Merge PR.
 ## Create a release

diff --git a/doc-requirements.txt b/doc-requirements.txt
@@ -1,153 +1,61 @@
 #
-# This file is autogenerated by pip-compile with Python 3.9
+# This file is autogenerated by pip-compile with Python 3.10
 # by the following command:
 #
-#    pip-compile doc-requirements.in
+#    pip-compile --annotation-style=line doc-requirements.in
 #
-alabaster==0.7.13
-    # via sphinx
-astroid==2.15.6
-    # via sphinx-autoapi
-babel==2.12.1
-    # via sphinx
-beautifulsoup4==4.12.2
-    # via
-    #   furo
-    #   sphinx-code-include
-certifi==2023.7.22
-    # via requests
-cfgv==3.4.0
-    # via pre-commit
-charset-normalizer==3.2.0
-    # via requests
-codespell==2.2.6
-    # via -r doc-requirements.in
-distlib==0.3.7
-    # via virtualenv
-docutils==0.17.1
-    # via
-    #   sphinx
-    #   sphinx-panels
-    #   sphinx-tabs
-filelock==3.12.4
-    # via virtualenv
-furo @ git+https://github.com/flyteorg/furo@main
-    # via -r doc-requirements.in
-identify==2.5.29
-    # via pre-commit
-idna==3.4
-    # via requests
-imagesize==1.4.1
-    # via sphinx
-importlib-metadata==6.8.0
-    # via sphinx
-jinja2==3.0.3
-    # via
-    #   sphinx
-    #   sphinx-autoapi
-    #   sphinx-tabs
-lazy-object-proxy==1.9.0
-    # via astroid
-markupsafe==2.1.3
-    # via jinja2
-nodeenv==1.8.0
-    # via pre-commit
-packaging==23.1
-    # via sphinx
-platformdirs==3.10.0
-    # via virtualenv
-pre-commit==3.4.0
-    # via sphinx-tags
-pygments==2.16.1
-    # via
-    #   furo
-    #   sphinx
-    #   sphinx-prompt
-    #   sphinx-tabs
-pyyaml==6.0.1
-    # via
-    #   pre-commit
-    #   sphinx-autoapi
-requests==2.31.0
-    # via
-    #   sphinx
-    #   sphinxcontrib-youtube
-six==1.16.0
-    # via
-    #   sphinx-code-include
-    #   sphinxext-remoteliteralinclude
-snowballstemmer==2.2.0
-    # via sphinx
-soupsieve==2.5
-    # via beautifulsoup4
-sphinx==4.5.0
-    # via
-    #   -r doc-requirements.in
-    #   furo
-    #   sphinx-autoapi
-    #   sphinx-basic-ng
-    #   sphinx-code-include
-    #   sphinx-copybutton
-    #   sphinx-fontawesome
-    #   sphinx-issues
-    #   sphinx-panels
-    #   sphinx-prompt
-    #   sphinx-tabs
-    #   sphinx-tags
-    #   sphinxcontrib-video
-    #   sphinxcontrib-youtube
-sphinx-autoapi==2.0.1
-    # via -r doc-requirements.in
-sphinx-basic-ng==1.0.0b2
-    # via furo
-sphinx-code-include==1.1.1
-    # via -r doc-requirements.in
-sphinx-copybutton==0.5.2
-    # via -r doc-requirements.in
-sphinx-fontawesome==0.0.6
-    # via -r doc-requirements.in
-sphinx-issues==3.0.1
-    # via -r doc-requirements.in
-sphinx-panels==0.6.0
-    # via -r doc-requirements.in
-sphinx-prompt==1.5.0
-    # via -r doc-requirements.in
-sphinx-tabs==3.4.0
-    # via -r doc-requirements.in
-sphinx-tags==0.2.1
-    # via -r doc-requirements.in
-sphinxcontrib-applehelp==1.0.4
-    # via sphinx
-sphinxcontrib-devhelp==1.0.2
-    # via sphinx
-sphinxcontrib-htmlhelp==2.0.1
-    # via sphinx
-sphinxcontrib-jsmath==1.0.1
-    # via sphinx
-sphinxcontrib-mermaid==0.9.2
-    # via -r doc-requirements.in
-sphinxcontrib-qthelp==1.0.3
-    # via sphinx
-sphinxcontrib-serializinghtml==1.1.5
-    # via sphinx
-sphinxcontrib-video==0.2.0
-    # via -r doc-requirements.in
-sphinxcontrib-youtube==1.2.0
-    # via -r doc-requirements.in
-sphinxext-remoteliteralinclude==0.4.0
-    # via -r doc-requirements.in
-typing-extensions==4.8.0
-    # via astroid
-unidecode==1.3.6
-    # via sphinx-autoapi
-urllib3==2.0.6
-    # via requests
-virtualenv==20.24.5
-    # via pre-commit
-wrapt==1.15.0
-    # via astroid
-zipp==3.17.0
-    # via importlib-metadata
+alabaster==0.7.13         # via sphinx
+astroid==3.0.1            # via sphinx-autoapi
+babel==2.13.1             # via sphinx
+beautifulsoup4==4.12.2    # via furo, sphinx-code-include
+certifi==2023.11.17       # via requests
+cfgv==3.4.0               # via pre-commit
+charset-normalizer==3.3.2  # via requests
+codespell==2.2.6          # via -r doc-requirements.in
+distlib==0.3.7            # via virtualenv
+docutils==0.17.1          # via sphinx, sphinx-panels, sphinx-tabs
+filelock==3.13.1          # via virtualenv
+furo @ git+https://github.com/flyteorg/furo@main  # via -r doc-requirements.in
+identify==2.5.32          # via pre-commit
+idna==3.6                 # via requests
+imagesize==1.4.1          # via sphinx
+jinja2==3.0.3             # via sphinx, sphinx-autoapi, sphinx-tabs
+markupsafe==2.1.3         # via jinja2
+nodeenv==1.8.0            # via pre-commit
+packaging==23.2           # via sphinx
+platformdirs==4.1.0       # via virtualenv
+pre-commit==3.5.0         # via sphinx-tags
+pygments==2.17.2          # via furo, sphinx, sphinx-prompt, sphinx-tabs
+pyyaml==6.0.1             # via pre-commit, sphinx-autoapi
+requests==2.31.0          # via sphinx, sphinxcontrib-youtube
+six==1.16.0               # via sphinx-code-include, sphinxext-remoteliteralinclude
+snowballstemmer==2.2.0    # via sphinx
+soupsieve==2.5            # via beautifulsoup4
+sphinx==4.5.0             # via -r doc-requirements.in, furo, sphinx-autoapi, sphinx-basic-ng, sphinx-code-include, sphinx-copybutton, sphinx-fontawesome, sphinx-issues, sphinx-panels, sphinx-prompt, sphinx-tabs, sphinx-tags, sphinxcontrib-video, sphinxcontrib-youtube, sphinxext-remoteliteralinclude
+sphinx-autoapi==2.0.1     # via -r doc-requirements.in
+sphinx-basic-ng==1.0.0b2  # via furo
+sphinx-code-include==1.1.1  # via -r doc-requirements.in
+sphinx-copybutton==0.5.2  # via -r doc-requirements.in
+sphinx-fontawesome==0.0.6  # via -r doc-requirements.in
+sphinx-issues==3.0.1      # via -r doc-requirements.in
+sphinx-panels==0.6.0      # via -r doc-requirements.in
+sphinx-prompt==1.5.0      # via -r doc-requirements.in
+sphinx-tabs==3.4.0        # via -r doc-requirements.in
+sphinx-tags==0.2.1        # via -r doc-requirements.in
+sphinxcontrib-applehelp==1.0.4  # via sphinx
+sphinxcontrib-devhelp==1.0.2  # via sphinx
+sphinxcontrib-htmlhelp==2.0.1  # via sphinx
+sphinxcontrib-jsmath==1.0.1  # via sphinx
+sphinxcontrib-mermaid==0.9.2  # via -r doc-requirements.in
+sphinxcontrib-qthelp==1.0.3  # via sphinx
+sphinxcontrib-serializinghtml==1.1.5  # via sphinx
+sphinxcontrib-video==0.2.0  # via -r doc-requirements.in
+sphinxcontrib-youtube==1.2.0  # via -r doc-requirements.in
+sphinxext-remoteliteralinclude==0.4.0  # via -r doc-requirements.in
+typing-extensions==4.8.0  # via astroid
+unidecode==1.3.7          # via sphinx-autoapi
+urllib3==2.1.0            # via requests
+virtualenv==20.25.0       # via pre-commit
 
 # The following packages are considered to be unsafe in a requirements file:
 # setuptools
diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml
@@ -0,0 +1,17 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "mambaforge-22.9"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+conda:
+  environment: monodocs-environment.yaml
diff --git a/docs/Makefile b/docs/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)
+
+clean:
+	rm -rf _build _src api flytectl flytekit flytesnacks protos examples
diff --git a/docs/_ext/__init__.py b/docs/_ext/__init__.py