From 266a37b109376ab3b06851a0cfcb83228a03305d Mon Sep 17 00:00:00 2001 From: Thomas Nicholas Date: Thu, 5 Jan 2023 13:46:40 -0500 Subject: [PATCH 1/4] try to fix code links in docs --- ci/doc.yml | 2 ++ docs/source/conf.py | 18 ++++++++++++++---- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/ci/doc.yml b/ci/doc.yml index fc9baeb0..ce502c0f 100644 --- a/ci/doc.yml +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index f310e35d..06eb6d9d 100644 --- a/docs/source/conf.py +++ b/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}" ) From 16a62cef3576109e162387c88cb29b981d1944f6 Mon Sep 17 00:00:00 2001 From: Thomas Nicholas Date: Fri, 6 Jan 2023 11:51:33 -0500 Subject: [PATCH 2/4] add currentmodule datatree command to get links to api docs working --- docs/source/data-structures.rst | 2 ++ docs/source/hierarchical-data.rst | 2 ++ docs/source/index.rst | 2 ++ docs/source/installation.rst | 2 ++ docs/source/io.rst | 2 ++ docs/source/quick-overview.rst | 2 ++ docs/source/terminology.rst | 1 + docs/source/tutorial.rst | 2 ++ 8 files changed, 15 insertions(+) diff --git a/docs/source/data-structures.rst b/docs/source/data-structures.rst index 37bfb12c..23dd8edf 100644 --- a/docs/source/data-structures.rst +++ b/docs/source/data-structures.rst @@ -1,3 +1,5 @@ +.. currentmodule:: datatree + .. _data structures: Data Structures diff --git a/docs/source/hierarchical-data.rst b/docs/source/hierarchical-data.rst index e474d189..9d197eed 100644 --- a/docs/source/hierarchical-data.rst +++ b/docs/source/hierarchical-data.rst @@ -1,3 +1,5 @@ +.. currentmodule:: datatree + .. _hierarchical-data: Working With Hierarchical Data diff --git a/docs/source/index.rst b/docs/source/index.rst index 9fd21c95..d13a0edf 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,3 +1,5 @@ +.. currentmodule:: datatree + Datatree ======== diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 6cab417e..b2682743 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -1,3 +1,5 @@ +.. currentmodule:: datatree + ============ Installation ============ diff --git a/docs/source/io.rst b/docs/source/io.rst index dee4ba80..2f2dabf9 100644 --- a/docs/source/io.rst +++ b/docs/source/io.rst @@ -1,3 +1,5 @@ +.. currentmodule:: datatree + .. _io: Reading and Writing Files diff --git a/docs/source/quick-overview.rst b/docs/source/quick-overview.rst index 5ec2194a..cdf62592 100644 --- a/docs/source/quick-overview.rst +++ b/docs/source/quick-overview.rst @@ -1,3 +1,5 @@ +.. currentmodule:: datatree + ############## Quick overview ############## diff --git a/docs/source/terminology.rst b/docs/source/terminology.rst index a6b1cc8f..e481a01a 100644 --- a/docs/source/terminology.rst +++ b/docs/source/terminology.rst @@ -1,4 +1,5 @@ .. currentmodule:: datatree + .. _terminology: This page extends `xarray's page on terminology `_. diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index e70044c2..6e33bd36 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -1,3 +1,5 @@ +.. currentmodule:: datatree + ======== Tutorial ======== From 2e80899d5ddf562a9a31b3f12a42aa44f5972099 Mon Sep 17 00:00:00 2001 From: Thomas Nicholas Date: Fri, 6 Jan 2023 11:54:50 -0500 Subject: [PATCH 3/4] add some intersphinx links to xarray API --- docs/source/hierarchical-data.rst | 2 +- docs/source/quick-overview.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/hierarchical-data.rst b/docs/source/hierarchical-data.rst index 9d197eed..282e1ffe 100644 --- a/docs/source/hierarchical-data.rst +++ b/docs/source/hierarchical-data.rst @@ -33,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. diff --git a/docs/source/quick-overview.rst b/docs/source/quick-overview.rst index cdf62592..4743b089 100644 --- a/docs/source/quick-overview.rst +++ b/docs/source/quick-overview.rst @@ -7,8 +7,8 @@ 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 `_ page): From df29c259f7e853d7d9be492213d205315b30e7ad Mon Sep 17 00:00:00 2001 From: Thomas Nicholas Date: Fri, 6 Jan 2023 11:56:55 -0500 Subject: [PATCH 4/4] whatsnew --- docs/source/whats-new.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/whats-new.rst b/docs/source/whats-new.rst index 93fad0e1..8d46de4b 100644 --- a/docs/source/whats-new.rst +++ b/docs/source/whats-new.rst @@ -50,6 +50,8 @@ Bug fixes - Fix bug with :py:meth:`DataTree.relative_to` method (:issue:`133`, :pull:`160`). By `Tom Nicholas `_. +- Fix links to API docs in all documentation (:pull:`183`). + By `Tom Nicholas `_. Documentation ~~~~~~~~~~~~~