Move docs to readthedocs (#797)

* update config for readthedocs

* remove sphinx-multiversion config

* Clean up config files

* Update gitignore

* update build files

Author: tcmetzger

.github/workflows/docs-publish.yml

@@ -27,6 +27,7 @@ share/python-wheels/
 *.egg
 MANIFEST
 xrspatial/.version
+xrspatial/_version.py
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

.gitignore

@@ -0,0 +1,26 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - [docs, tests]

.readthedocs.yml

@@ -1,24 +1,20 @@
-# Makefile for Sphinx documentation
+# Minimal makefile for Sphinx documentation
+#
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = python -m sphinx
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
 
-.PHONY: help clean html
-
+# Put it first so that "make" without argument is like "make help".
 help:
-	@echo "Please use 'make <target>' where <target> is one of"
-	@echo "  clean            to clear all built documentation files"
-	@echo "  html             to make all standalone HTML files"
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-clean:
-	-rm -rf $(BUILDDIR)/*
+.PHONY: help Makefile
 
-html: clean
-	( THEME=sphinx_rtd_theme sphinx-multiversion $(SOURCEDIR) $(BUILDDIR)/html )
-	( THEME=pydata_sphinx_theme sphinx-multiversion $(SOURCEDIR) $(BUILDDIR)/html )
+# 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)
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

docs/Makefile

@@ -10,34 +10,26 @@ if "%SPHINXBUILD%" == "" (
 set SOURCEDIR=source
 set BUILDDIR=build
 
-if "%1" == "" goto help
-
-if "%1" == "help" (
-	:help
-	echo.Please use `make ^<target^>` where ^<target^> is one of
-	echo.  clean             to clear all built documentation files
-	echo.  html              to make all standalone HTML files
-
-	goto end
-)
-
-if "%1" == "clean" (
-	rmdir %BUILDDIR% /s /q
-	goto end
+%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.https://www.sphinx-doc.org/
+	exit /b 1
 )
 
-if "%1" == "html" (
-	set THEME=sphinx_rtd_theme
-	sphinx-multiversion %SOURCEDIR% %BUILDDIR%\html
+if "%1" == "" goto help
 
-	set THEME=pydata_sphinx_theme
-	sphinx-multiversion %SOURCEDIR% %BUILDDIR%\html
-	%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
 
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
-	goto end
-)
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
 :end
+popd

docs/make.bat

@@ -8,6 +8,7 @@
 
 # -- Path setup --------------------------------------------------------------
 
+from datetime import datetime
 import json
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -23,7 +24,7 @@
 # -- Project information -----------------------------------------------------
 
 project = u'xarray_spatial'
-copyright = u'2020-2022, makepath'
+copyright = u'2020-{}, makepath'.format(datetime.now().year)
 author = u'makepath'
 
 version = release = xrspatial.__version__
@@ -66,7 +67,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -82,38 +83,26 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-if os.getenv('THEME') == 'sphinx_rtd_theme':
-    html_theme = 'sphinx_rtd_theme'
-else:
-    html_theme = 'pydata_sphinx_theme'
+
+html_theme = 'pydata_sphinx_theme'
 
 html_logo = '_static/img/Xarray-Spatial-logo.svg'
 
 html_favicon = '_static/img/favicon.ico'
 
-# sphinx-multiversion config
-smv_branch_whitelist = 'master'
-if os.getenv('THEME') == 'sphinx_rtd_theme':
-    smv_tag_whitelist = r'^v([0-9]\.[2-9]\.[0-9])'
-else:
-    smv_tag_whitelist = r'^v([0-9]\.[2-9]\.[0-9])'
-
-# Load releases
-with open("releases.json") as f:
-    releases = json.load(f)
-
 # 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.
 #
 html_theme_options = {
     "external_links": [],
     "github_url": "https://github.com/makepath/xarray-spatial",
+    "navbar_end": ["navbar-icon-links"],
 }
 
 html_context = {
     'css_files': ['_static/css/styles.css'],
-    'releases': [(release, url) for release, url in releases.items()],
+    "default_mode": "light",
 }
 
 autosummary_generate = True
@@ -133,7 +122,6 @@
 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
 # 'searchbox.html']``.
 #
-# html_sidebars = {}
 
 
 # -- Options for HTMLHelp output ---------------------------------------------

docs/source/conf.py

@@ -34,6 +34,7 @@ console_scripts =
 
 [options.extras_require]
 doc =
+    dask[dataframe]
     geopandas
     Jinja2 >=2.11
     ipykernel
@@ -43,7 +44,6 @@ doc =
     pandoc
     pydata_sphinx_theme
     sphinx
-    sphinx-multiversion
     sphinx-panels
     sphinx_rtd_theme
 examples =