doc: switch to sphinx-book theme

Author: benbovy

ci/environment.yml

@@ -11,3 +11,5 @@ dependencies:
   - pys2index
   - pytest
   - pytest-cov
+  - pydata-sphinx-theme=0.15.4
+  - sphinx-book-theme=1.1.4

doc/_static/style.css

@@ -0,0 +1,55 @@
+
+code.literal {
+  background-color: unset;
+  border: unset;
+}
+
+.xr-wrap {
+  /* workaround when (ipy)widgets are present in output cells
+   * https://github.com/xarray-contrib/xarray-indexes/issues/14
+   * only rely on pydata-sphinx-theme variables here!
+  */
+  --xr-font-color0: var(--pst-color-text-base);
+  --xr-font-color2: var(--pst-color-text-base);
+  --xr-font-color3: var(--pst-color-text-base);
+  --xr-border-color: hsl(from var(--pst-color-text-base) h s calc(l + 40));
+  --xr-disabled-color: hsl(from var(--pst-color-text-base) h s calc(l + 40));
+  --xr-background-color: var(--pst-color-on-background);
+  --xr-background-color-row-even: hsl(
+    from var(--pst-color-on-background) h s calc(l - 5)
+  );
+  --xr-background-color-row-odd: hsl(
+    from var(--pst-color-on-background) h s calc(l - 15)
+  );
+
+  font-size: 0.9em;
+  margin-left: 1.25em;
+}
+
+html[data-theme="dark"] .xr-wrap {
+  --xr-border-color: hsl(from var(--pst-color-text-base) h s calc(l - 40));
+  --xr-disabled-color: hsl(from var(--pst-color-text-base) h s calc(l - 40));
+  --xr-background-color-row-even: hsl(
+    from var(--pst-color-on-background) h s calc(l + 5)
+  );
+  --xr-background-color-row-odd: hsl(
+    from var(--pst-color-on-background) h s calc(l + 15)
+  );
+}
+
+.xr-array-wrap,
+.xr-var-data,
+.xr-var-preview {
+  /* font-size: 0.9em; */
+}
+.gp {
+  color: darkorange;
+}
+
+/* workaround Pydata Sphinx theme using light colors for widget cell outputs in dark-mode */
+/* works for many widgets but not for Xarray html reprs */
+/* https://github.com/pydata/pydata-sphinx-theme/issues/2189 */
+html[data-theme="dark"] .output_area.rendered_html:has(div.xr-wrap) {
+  background-color: var(--pst-color-on-background) !important;
+  color: var(--pst-color-text-base) !important;
+}

doc/conf.py

@@ -66,17 +66,18 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
-
-# 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 = {
-#    "github_url": "https://github.com/xarray-contrib/xoak",
-#    "use_edit_page_button": True,
-#    "search_bar_position": "navbar",
-# }
-
+html_theme = "sphinx_book_theme"
+html_title = "Xoak"
+
+html_theme_options = dict(
+    repository_url="https://github.com/xarray-contrib/xoak",
+    repository_branch="master",
+    path_to_docs="doc",
+    use_edit_page_button=True,
+    use_repository_button=True,
+    use_issues_button=True,
+    home_page_in_toc=False,
+)
 
 html_context = {
     "github_user": "xarray-contrib",
@@ -85,22 +86,11 @@
     "doc_path": "doc",
 }
 
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+html_css_files = ["style.css"]
 
-
-# Enable notebook execution
-# https://nbsphinx.readthedocs.io/en/0.4.2/never-execute.html
-# nbsphinx_execute = 'auto'
-# Allow errors in all notebooks by
-# nbsphinx_allow_errors = True
 nbsphinx_kernel_name = "python3"
-
-# Disable cell timeout
 nbsphinx_timeout = -1
-
 nbsphinx_prolog = """
 {% set docname = env.doc2path(env.docname, base=None) %}
 

doc/examples/dask_support.ipynb

@@ -22,8 +22,7 @@
     "import numpy as np\n",
     "import xarray as xr\n",
     "import xoak\n",
-    "\n",
-    "xr.set_options(display_style='text');"
+    "\n"
    ]
   },
   {

doc/examples/introduction.ipynb

@@ -18,8 +18,7 @@
     "import numpy as np\n",
     "import xarray as xr\n",
     "import xoak\n",
-    "\n",
-    "xr.set_options(display_style='text');"
+    "\n"
    ]
   },
   {