Use xarray docs theme instead of pangeo

ci/doc.yml

@@ -6,14 +6,18 @@ dependencies:
   - python>=3.8
   - netcdf4
   - scipy
-  - sphinx
+  - sphinx>=4.2.0
   - sphinx-copybutton
-  - numpydoc
+  - sphinx-panels
   - sphinx-autosummary-accessors
+  - sphinx-book-theme >= 0.0.38
+  - pydata-sphinx-theme>=0.4.3
+  - numpydoc
   - ipython
   - h5netcdf
   - zarr
   - pip:
       - git+https://github.com/xarray-contrib/datatree
-      - pangeo-sphinx-book-theme
+      - sphinxext-rediraffe
+      - sphinxext-opengraph
       - xarray>=2022.05.0.dev0

docs/Makefile

@@ -19,11 +19,12 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) sou
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html rtdhtml dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
 
 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 "  dirhtml    to make HTML files named index.html in directories"
 	@echo "  singlehtml to make a single large HTML file"
 	@echo "  pickle     to make pickle files"
@@ -54,6 +55,11 @@ html:
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+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."
+
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo

docs/source/conf.py

@@ -45,6 +45,9 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.extlinks",
     "sphinx.ext.napoleon",
+    "sphinx_copybutton",
+    "sphinxext.opengraph",
+    "sphinx_autosummary_accessors",
     "IPython.sphinxext.ipython_console_highlighting",
     "IPython.sphinxext.ipython_directive",
 ]
@@ -131,7 +134,11 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "pangeo_sphinx_book_theme"
+html_theme = "sphinx_book_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 = {
     "repository_url": "https://github.com/xarray-contrib/datatree",
     "repository_branch": "main",
@@ -141,11 +148,6 @@
     "use_edit_page_button": True,
 }
 
-# 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 = {}
-
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
 
@@ -168,7 +170,7 @@
 # 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_static_path = ["_static"]
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -291,3 +293,53 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 # texinfo_no_detailmenu = False
+
+
+# based on numpy doc/source/conf.py
+def linkcode_resolve(domain, info):
+    """
+    Determine the URL corresponding to Python object
+    """
+    if domain != "py":
+        return None
+
+    modname = info["module"]
+    fullname = info["fullname"]
+
+    submod = sys.modules.get(modname)
+    if submod is None:
+        return None
+
+    obj = submod
+    for part in fullname.split("."):
+        try:
+            obj = getattr(obj, part)
+        except AttributeError:
+            return None
+
+    try:
+        fn = inspect.getsourcefile(inspect.unwrap(obj))
+    except TypeError:
+        fn = None
+    if not fn:
+        return None
+
+    try:
+        source, lineno = inspect.getsourcelines(obj)
+    except OSError:
+        lineno = None
+
+    if lineno:
+        linespec = f"#L{lineno}-L{lineno + len(source) - 1}"
+    else:
+        linespec = ""
+
+    fn = os.path.relpath(fn, start=os.path.dirname(xarray.__file__))
+
+    if "+" in xarray.__version__:
+        return f"https://github.com/xarray-contrib/datatree/blob/main/datatree/{fn}{linespec}"
+    else:
+        return (
+            f"https://github.com/xarray-contrib/datatree/blob/"
+            f"v{datatree.__version__}/xarray/{fn}{linespec}"
+        )

docs/source/whats-new.rst

@@ -48,6 +48,8 @@ Documentation
 
 - Added ``Reading and Writing Files`` page. (:pull:`158`)
   By `Tom Nicholas <https://github.com/TomNicholas>`_.
+- Changed docs theme to match xarray's main documentation. (:pull:`173`)
+  By `Tom Nicholas <https://github.com/TomNicholas>`_.
 
 Internal Changes
 ~~~~~~~~~~~~~~~~