Try to fix code links in docs (#183)

* try to fix code links in docs

* add currentmodule datatree command to get links to api docs working

* add some intersphinx links to xarray API

* whatsnew

Author: TomNicholas

ci/doc.yml

@@ -11,6 +11,8 @@ dependencies:
   - sphinx-panels
   - sphinx-autosummary-accessors
   - sphinx-book-theme >= 0.0.38
+  - nbsphinx
+  - sphinxcontrib-srclinks
   - pydata-sphinx-theme>=0.4.3
   - numpydoc
   - ipython

docs/source/conf.py

@@ -13,6 +13,7 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+import inspect
 import os
 import sys
 
@@ -41,6 +42,7 @@
     "numpydoc",
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
+    "sphinx.ext.linkcode",
     "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
     "sphinx.ext.extlinks",
@@ -50,6 +52,8 @@
     "sphinx_autosummary_accessors",
     "IPython.sphinxext.ipython_console_highlighting",
     "IPython.sphinxext.ipython_directive",
+    "nbsphinx",
+    "sphinxcontrib.srclinks",
 ]
 
 extlinks = {
@@ -76,6 +80,11 @@
 copyright = "2021 onwards, Tom Nicholas and its Contributors"
 author = "Tom Nicholas"
 
+html_show_sourcelink = True
+srclink_project = "https://github.com/xarray-contrib/datatree"
+srclink_branch = "main"
+srclink_src_path = "docs/source"
+
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
@@ -127,6 +136,7 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3.8/", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
     "xarray": ("https://xarray.pydata.org/en/stable/", None),
 }
 
@@ -142,7 +152,7 @@
 html_theme_options = {
     "repository_url": "https://github.com/xarray-contrib/datatree",
     "repository_branch": "main",
-    "path_to_docs": "doc",
+    "path_to_docs": "docs/source",
     "use_repository_button": True,
     "use_issues_button": True,
     "use_edit_page_button": True,
@@ -334,12 +344,12 @@ def linkcode_resolve(domain, info):
     else:
         linespec = ""
 
-    fn = os.path.relpath(fn, start=os.path.dirname(xarray.__file__))
+    fn = os.path.relpath(fn, start=os.path.dirname(datatree.__file__))
 
-    if "+" in xarray.__version__:
+    if "+" in datatree.__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}"
+            f"v{datatree.__version__}/datatree/{fn}{linespec}"
         )

docs/source/data-structures.rst

@@ -1,3 +1,5 @@
+.. currentmodule:: datatree
+
 .. _data structures:
 
 Data Structures

docs/source/hierarchical-data.rst

@@ -1,3 +1,5 @@
+.. currentmodule:: datatree
+
 .. _hierarchical-data:
 
 Working With Hierarchical Data
@@ -31,7 +33,7 @@ Examples of data which one might want organise in a grouped or hierarchical mann
 
 or even any combination of the above.
 
-Often datasets like this cannot easily fit into a single ``xarray.Dataset`` object,
+Often datasets like this cannot easily fit into a single :py:class:`xarray.Dataset` object,
 or are more usefully thought of as groups of related ``xarray.Dataset`` objects.
 For this purpose we provide the :py:class:`DataTree` class.
 

docs/source/index.rst

@@ -1,3 +1,5 @@
+.. currentmodule:: datatree
+
 Datatree
 ========
 

docs/source/installation.rst

@@ -1,3 +1,5 @@
+.. currentmodule:: datatree
+
 ============
 Installation
 ============

docs/source/io.rst

@@ -1,3 +1,5 @@
+.. currentmodule:: datatree
+
 .. _io:
 
 Reading and Writing Files

docs/source/quick-overview.rst

@@ -1,12 +1,14 @@
+.. currentmodule:: datatree
+
 ##############
 Quick overview
 ##############
 
 DataTrees
 ---------
 
-:py:class:`DataTree` is a tree-like container of ``DataArray`` objects, organised into multiple mutually alignable groups.
-You can think of it like a (recursive) ``dict`` of ``Dataset`` objects.
+:py:class:`DataTree` is a tree-like container of :py:class:`xarray.DataArray` objects, organised into multiple mutually alignable groups.
+You can think of it like a (recursive) ``dict`` of :py:class:`xarray.Dataset` objects.
 
 Let's first make some example xarray datasets (following on from xarray's
 `quick overview <https://docs.xarray.dev/en/stable/getting-started-guide/quick-overview.html>`_ page):

docs/source/terminology.rst

@@ -1,4 +1,5 @@
 .. currentmodule:: datatree
+
 .. _terminology:
 
 This page extends `xarray's page on terminology <https://docs.xarray.dev/en/stable/user-guide/terminology.html>`_.

docs/source/tutorial.rst

@@ -1,3 +1,5 @@
+.. currentmodule:: datatree
+
 ========
 Tutorial
 ========