Use napoleon instead of numpydoc (xarray doc alignment), and fixes (#298

)

* Use napoleon instead of numpydoc, and fixes

* docs

* A mypy ignore for pre-commit run --all-files

* Updated whats-new.rst

.gitignore

@@ -131,3 +131,5 @@ dmypy.json
 
 # version
 _version.py
+
+.vscode

ci/doc.yml

@@ -13,8 +13,8 @@ dependencies:
   - sphinx-book-theme >= 0.0.38
   - nbsphinx
   - sphinxcontrib-srclinks
+  - pickleshare
   - pydata-sphinx-theme>=0.4.3
-  - numpydoc
   - ipython
   - h5netcdf
   - zarr

datatree/mapping.py

@@ -282,7 +282,7 @@ def wrapper(*args, **kwargs):
 def add_note(err: BaseException, msg: str) -> None:
     # TODO: remove once python 3.10 can be dropped
     if sys.version_info < (3, 11):
-        err.__notes__ = getattr(err, "__notes__", []) + [msg]
+        err.__notes__ = getattr(err, "__notes__", []) + [msg]  # type: ignore[attr-defined]
     else:
         err.add_note(msg)
 

docs/README.md

@@ -0,0 +1,14 @@
+# README - docs
+
+## Build the documentation locally
+
+```bash
+cd docs # From project's root
+make clean
+rm -rf source/generated # remove autodoc artefacts, that are not removed by `make clean`
+make html
+```
+
+## Access the documentation locally
+
+Open `docs/_build/html/index.html` in a web browser

docs/source/api.rst

@@ -249,9 +249,7 @@ Methods copied from :py:class:`numpy.ndarray` objects, here applying to the data
    DataTree.clip
    DataTree.conj
    DataTree.conjugate
-   DataTree.imag
    DataTree.round
-   DataTree.real
    DataTree.rank
 
 Reshaping and reorganising

docs/source/conf.py

@@ -39,7 +39,6 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
-    "numpydoc",
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
     "sphinx.ext.linkcode",
@@ -57,15 +56,78 @@
 ]
 
 extlinks = {
-    "issue": ("https://github.com/TomNicholas/datatree/issues/%s", "GH#"),
-    "pull": ("https://github.com/TomNicholas/datatree/pull/%s", "GH#"),
+    "issue": ("https://github.com/xarray-contrib/datatree/issues/%s", "GH#%s"),
+    "pull": ("https://github.com/xarray-contrib/datatree/pull/%s", "GH#%s"),
 }
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates", sphinx_autosummary_accessors.templates_path]
 
 # Generate the API documentation when building
 autosummary_generate = True
 
+
+# Napoleon configurations
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_param = False
+napoleon_use_rtype = False
+napoleon_preprocess_types = True
+napoleon_type_aliases = {
+    # general terms
+    "sequence": ":term:`sequence`",
+    "iterable": ":term:`iterable`",
+    "callable": ":py:func:`callable`",
+    "dict_like": ":term:`dict-like <mapping>`",
+    "dict-like": ":term:`dict-like <mapping>`",
+    "path-like": ":term:`path-like <path-like object>`",
+    "mapping": ":term:`mapping`",
+    "file-like": ":term:`file-like <file-like object>`",
+    # special terms
+    # "same type as caller": "*same type as caller*",  # does not work, yet
+    # "same type as values": "*same type as values*",  # does not work, yet
+    # stdlib type aliases
+    "MutableMapping": "~collections.abc.MutableMapping",
+    "sys.stdout": ":obj:`sys.stdout`",
+    "timedelta": "~datetime.timedelta",
+    "string": ":class:`string <str>`",
+    # numpy terms
+    "array_like": ":term:`array_like`",
+    "array-like": ":term:`array-like <array_like>`",
+    "scalar": ":term:`scalar`",
+    "array": ":term:`array`",
+    "hashable": ":term:`hashable <name>`",
+    # matplotlib terms
+    "color-like": ":py:func:`color-like <matplotlib.colors.is_color_like>`",
+    "matplotlib colormap name": ":doc:`matplotlib colormap name <matplotlib:gallery/color/colormap_reference>`",
+    "matplotlib axes object": ":py:class:`matplotlib axes object <matplotlib.axes.Axes>`",
+    "colormap": ":py:class:`colormap <matplotlib.colors.Colormap>`",
+    # objects without namespace: xarray
+    "DataArray": "~xarray.DataArray",
+    "Dataset": "~xarray.Dataset",
+    "Variable": "~xarray.Variable",
+    "DatasetGroupBy": "~xarray.core.groupby.DatasetGroupBy",
+    "DataArrayGroupBy": "~xarray.core.groupby.DataArrayGroupBy",
+    # objects without namespace: numpy
+    "ndarray": "~numpy.ndarray",
+    "MaskedArray": "~numpy.ma.MaskedArray",
+    "dtype": "~numpy.dtype",
+    "ComplexWarning": "~numpy.ComplexWarning",
+    # objects without namespace: pandas
+    "Index": "~pandas.Index",
+    "MultiIndex": "~pandas.MultiIndex",
+    "CategoricalIndex": "~pandas.CategoricalIndex",
+    "TimedeltaIndex": "~pandas.TimedeltaIndex",
+    "DatetimeIndex": "~pandas.DatetimeIndex",
+    "Series": "~pandas.Series",
+    "DataFrame": "~pandas.DataFrame",
+    "Categorical": "~pandas.Categorical",
+    "Path": "~~pathlib.Path",
+    # objects with abbreviated namespace (from pandas)
+    "pd.Index": "~pandas.Index",
+    "pd.NaT": "~pandas.NaT",
+}
+
 # The suffix of source filenames.
 source_suffix = ".rst"
 
@@ -177,11 +239,6 @@
 # pixels large.
 # html_favicon = None
 
-# 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"]
-
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 # html_last_updated_fmt = '%b %d, %Y'

docs/source/index.rst

@@ -50,7 +50,6 @@ Please raise any thoughts, issues, suggestions or bugs, no matter how small or l
    Reading and Writing Files <io>
    API Reference <api>
    Terminology <terminology>
-   How do I ... <howdoi>
    Contributing Guide <contributing>
    What's New <whats-new>
    GitHub repository <https://github.com/xarray-contrib/datatree>

docs/source/whats-new.rst

@@ -44,6 +44,9 @@ Bug fixes
 
 Documentation
 ~~~~~~~~~~~~~
+- Use ``napoleon`` instead of ``numpydoc`` to align with xarray documentation
+  (:issue:`284`, :pull:`298`).
+  By `Etienne Schalk <https://github.com/etienneschalk>`_.
 
 Internal Changes
 ~~~~~~~~~~~~~~~~
@@ -365,7 +368,7 @@ Breaking changes
 - Removes the option to delete all data in a node by assigning None to the node (in favour of deleting data by replacing
   the node's ``.ds`` attribute with an empty Dataset), or to create a new empty node in the same way (in favour of
   assigning an empty DataTree object instead).
-- Removes the ability to create a new node by assigning a ``Dataset`` object to ``DataTree.__setitem__`.
+- Removes the ability to create a new node by assigning a ``Dataset`` object to ``DataTree.__setitem__``.
 - Several other minor API changes such as ``.pathstr`` -> ``.path``, and ``from_dict``'s dictionary argument now being
   required. (:pull:`76`)
   By `Tom Nicholas <https://github.com/TomNicholas>`_.