Update docs theme, use sphinx-tabs for CPU/GPU examples (#394)

* Relocate doc source files

* Move conf.py to docs source folder

* Fix broken links in index

* Simplify environment file

* Start adding CPU/GPU tabs for code blocks

* Add GPU tabs to ML docs

* dask_ml_docs_fix

* Run pre-commit hooks

* Add TODOs to ML docs

* Start updating docs around code blocks

* Disable collapsible tabs

* Ignore docs build directory

* Use pip for RTD builds

* Attempt to install maven through apt for RTD builds

* Remove maven from pip requirements

* Add conda environment for convenience

Co-authored-by: Vibhu Jawa <vibhujawa@gmail.com>

Author: charlesbluca

.gitignore

@@ -58,3 +58,4 @@ dask_sql/jar
 .next/
 dask-worker-space/
 node_modules/
+docs/source/_build/

.readthedocs.yaml

@@ -1,10 +1,17 @@
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 version: 2
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.8"
+  apt_packages:
+    - maven
+
+sphinx:
+  configuration: docs/source/conf.py
 
 python:
-  version: 3.8
   install:
-    - method: setuptools
+    - requirements: docs/requirements-docs.txt
+    - method: pip
       path: .
-
-conda:
-  environment: docs/environment.yaml

docs/Makefile

@@ -5,8 +5,8 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
+SOURCEDIR     = source
+BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".
 help:

docs/environment.yaml

@@ -0,0 +1,21 @@
+name: dask-sql-docs
+channels:
+  - conda-forge
+  - nodefaults
+dependencies:
+  - python=3.9
+  - sphinx>=4.0.0
+  - sphinx-tabs
+  - dask-sphinx-theme>=2.0.3
+  - maven>=3.6.0
+  - dask>=2021.11.1
+  - pandas>=1.0.0
+  - fugue>=0.5.3
+  - jpype1>=1.0.2
+  - fastapi>=0.61.1
+  - uvicorn>=0.11.3
+  - tzlocal>=2.1
+  - prompt_toolkit
+  - pygments
+  - tabulate
+  - nest-asyncio

docs/environment.yml

@@ -7,8 +7,8 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set SOURCEDIR=.
-set BUILDDIR=_build
+set SOURCEDIR=source
+set BUILDDIR=build
 
 if "%1" == "" goto help
 
@@ -21,7 +21,7 @@ if errorlevel 9009 (
 	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/
+	echo.https://www.sphinx-doc.org/
 	exit /b 1
 )
 

docs/make.bat

@@ -0,0 +1,14 @@
+sphinx>=4.0.0
+sphinx-tabs
+dask-sphinx-theme>=2.0.3
+dask>=2021.11.1
+pandas>=1.0.0
+fugue>=0.5.3
+jpype1>=1.0.2
+fastapi>=0.61.1
+uvicorn>=0.11.3
+tzlocal>=2.1
+prompt_toolkit
+pygments
+tabulate
+nest-asyncio

docs/requirements-docs.txt

@@ -32,6 +32,7 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
+    "sphinx_tabs.tabs",
     "dask_sphinx_theme.ext.dask_config_sphinx_ext",
 ]
 
@@ -61,3 +62,6 @@
 
 # Do not show type mappings
 autodoc_typehints = "none"
+
+# disable collapsible tabs
+sphinx_tabs_disable_tab_closing = True