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}" ) 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..282e1ffe 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 @@ -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. 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..4743b089 100644 --- a/docs/source/quick-overview.rst +++ b/docs/source/quick-overview.rst @@ -1,3 +1,5 @@ +.. currentmodule:: datatree + ############## Quick overview ############## @@ -5,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): 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 ======== diff --git a/docs/source/whats-new.rst b/docs/source/whats-new.rst index 27ba0eb5..ed099fd9 100644 --- a/docs/source/whats-new.rst +++ b/docs/source/whats-new.rst @@ -52,6 +52,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 ~~~~~~~~~~~~~