📚 New theme & rearrangement of the docs (#4835)

.gitignore

@@ -65,10 +65,11 @@ dask-worker-space/
 
 # xarray specific
 doc/_build
-doc/generated
+generated/
 xarray/tests/data/*.grib.*.idx
 
 # Sync tools
 Icon*
 
 .ipynb_checkpoints
+doc/rasm.zarr

ci/requirements/doc.yml

@@ -20,16 +20,20 @@ dependencies:
   - numba
   - numpy>=1.17
   - pandas>=1.0
+  - pip
+  - pydata-sphinx-theme>=0.4.3
   - rasterio>=1.1
   - seaborn
   - setuptools
   - sparse
-  - sphinx>=3.3
-  - sphinx_rtd_theme>=0.4
   - sphinx-autosummary-accessors
+  - sphinx-book-theme >= 0.0.38
+  - sphinx-copybutton
+  - sphinx-panels
+  - sphinx>=3.3
   - zarr>=2.4
-  - pip
   - pip:
-      - scanpydoc
+      - sphinxext-rediraffe
+      - sphinxext-opengraph
       # relative to this file. Needs to be editable to be accepted.
       - -e ../..

doc/Makefile

@@ -19,6 +19,7 @@ I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"
+	@echo "  rtdhtml    Build html using same settings used on ReadtheDocs"
 	@echo "  livehtml   Make standalone HTML files and rebuild the documentation when a change is detected. Also includes a livereload enabled web server"
 	@echo "  dirhtml    to make HTML files named index.html in directories"
 	@echo "  singlehtml to make a single large HTML file"
@@ -58,6 +59,13 @@ html:
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+.PHONY: rtdhtml
+rtdhtml:
+	$(SPHINXBUILD) -T -j auto -E -W --keep-going -b html -d $(BUILDDIR)/doctrees -D language=en . $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+
 .PHONY: livehtml
 livehtml:
 	# @echo "$(SPHINXATUOBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html"

doc/_static/style.css

@@ -1,22 +1,3 @@
-@import url("theme.css");
-
-.wy-side-nav-search>a img.logo,
-.wy-side-nav-search .wy-dropdown>a img.logo {
-  width: 12rem
-}
-
-.wy-side-nav-search {
-  background-color: #eee;
-}
-
-.wy-side-nav-search>div.version {
-  display: none;
-}
-
-.wy-nav-top {
-  background-color: #555;
-}
-
 table.colwidths-given {
     table-layout: fixed;
     width: 100%;
@@ -25,3 +6,15 @@ table.docutils td {
     white-space: unset;
     word-wrap: break-word;
 }
+
+/* Reduce left and right margins */
+
+.container, .container-lg, .container-md, .container-sm, .container-xl {
+  max-width: 1600px !important;
+}
+
+/* Make sidebar sticky */
+
+.bd-sidebar {
+  position: sticky !important;
+}