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

[etienneschalk]

Motives

This issue aims to fix the build fail in #286

Also, hopefully it can help facilitate the merging into the xarray repo (documentation alignment)

Checklist

• [x] Closes #284
• [x] Tests added
• [x] Passes pre-commit run --all-files
• [x] New functions/methods are listed in api.rst
• [x] Changes are summarized in docs/source/whats-new.rst

Contents

Related to the issue

• Removed numpydoc CI dependency
• Added pickleshare CI dependency to fix warnings happening during make html locally, that could probably happen in the CI too
• Added a README.md describing how to build, clean and open the documentation
• Removed DataTree.imag and DataTree.real, they were raising warnings during make html
• Fixed the issue and pull extlinks with the new repo's URL
• Copy pasted all napoleon_ prefixed configuration variables in conf.py, from xarray repository: See https://github.com/pydata/xarray/blob/492aa076bd1812af71d68dc221312fb9a199d2d3/doc/conf.py#L118
• Removed the html_static_path in conf.py - it was raising a warning during doc build (unsure about this :question:)
• Removed howdoi in index.rst, to fix a warning
• Fixed a code literal in whats new.rst

• Misc

• Gitignore .vscode
• Added a ignore comment for mypy for existing code so that pre-commit run --all-files pass

Open points

• [x] Should the html_static_path in conf.py be kept? @TomNicholas

Notes

Locally, I pip install pickleshare to remove the warnings related to it

There are still warnings, I did not fix them all when I was unsure how to fix them. Here is the console output of the make html command:

make clean
rm -rf source/generated # remove autodoc artefacts, that are not removed by `make clean`
make html
rm -rf _build/*
sphinx-build -b html -d _build/doctrees   source _build/html
Running Sphinx v6.2.1
make making output directory... done
[autosummary] generating autosummary for: api.rst, contributing.rst, data-structures.rst, hierarchical-data.rst, index.rst, installation.rst, io.rst, quick-overview.rst, terminology.rst, tutorial.rst, whats-new.rst
htm[autosummary] generating autosummary for: /home/my_username/dev/datatree/docs/source/generated/datatree.DataTree.__delitem__.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.DataTree.__getitem__.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.DataTree.__setitem__.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.DataTree.all.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.DataTree.ancestors.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.DataTree.any.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.DataTree.argmax.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.DataTree.argmin.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.DataTree.argsort.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.DataTree.assign.rst, ..., /home/my_username/dev/datatree/docs/source/generated/datatree.DataTree.width.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.InvalidTreeError.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.NotFoundInTreeError.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.TreeIsomorphismError.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.map_over_subtree.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.open_datatree.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.register_datatree_accessor.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.testing.assert_equal.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.testing.assert_identical.rst, /home/my_username/dev/datatree/docs/source/generated/datatree.testing.assert_isomorphic.rst
loading intersphinx inventory from https://docs.python.org/3.8/objects.inv...
loading intersphinx inventory from https://numpy.org/doc/stable/objects.inv...
loading intersphinx inventory from https://xarray.pydata.org/en/stable/objects.inv...
lintersphinx inventory has moved: https://xarray.pydata.org/en/stable/objects.inv -> https://docs.xarray.dev/en/stable/objects.inv
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 11 source files that are out of date
updating environment: [new config] 157 added, 0 changed, 0 removed
reading sources... [100%] whats-new                                                                                                                                         
/home/my_username/dev/datatree/docs/source/data-structures.rst:6: WARNING: Duplicate explicit target name: "data structures".
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] whats-new                                                                                                                                          
/home/my_username/.pyenv/versions/3.10.12/envs/datatree-dev/lib/python3.10/site-packages/xarray/core/dataset.py:docstring of xarray.core.dataset.Dataset.interp:49: WARNING: unknown document: 'xarray-tutorial:fundamentals/02.2_manipulating_dimensions'
/home/my_username/.pyenv/versions/3.10.12/envs/datatree-dev/lib/python3.10/site-packages/xarray/core/dataset.py:docstring of xarray.core.dataset.Dataset.isel:94: WARNING: unknown document: 'xarray-tutorial:intermediate/indexing/indexing'
/home/my_username/.pyenv/versions/3.10.12/envs/datatree-dev/lib/python3.10/site-packages/xarray/core/dataset.py:docstring of xarray.core.dataset.Dataset.isel:96: WARNING: unknown document: 'xarray-tutorial:fundamentals/02.1_indexing_Basic'
/home/my_username/.pyenv/versions/3.10.12/envs/datatree-dev/lib/python3.10/site-packages/xarray/core/dataset.py:docstring of xarray.core.dataset.Dataset.map_blocks:43: WARNING: unknown document: 'xarray-tutorial:advanced/map_blocks/map_blocks'
/home/my_username/.pyenv/versions/3.10.12/envs/datatree-dev/lib/python3.10/site-packages/xarray/core/dataset.py:docstring of xarray.core.dataset.Dataset.sel:52: WARNING: unknown document: 'xarray-tutorial:intermediate/indexing/indexing'
/home/my_username/.pyenv/versions/3.10.12/envs/datatree-dev/lib/python3.10/site-packages/xarray/core/dataset.py:docstring of xarray.core.dataset.Dataset.sel:54: WARNING: unknown document: 'xarray-tutorial:fundamentals/02.1_indexing_Basic'
generating indices... genindex done
copying linked files... 
copying notebooks ... 
highlighting module code... [100%] datatree.treenode                                                                                                                        
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 7 warnings.

The HTML pages are in _build/html.

Build finished. The HTML pages are in _build/html.

[TomNicholas]

This looks great, thank you so much @etienneschalk !

WARNING: unknown document: 'xarray-tutorial:intermediate/indexing/indexing'

I think this is something going wrong in xarray upstream, let's ignore this one for now , see https://github.com/pydata/xarray/issues/8596. All the other warnings are also something to do with xarray-tutorial too.

Should the html_static_path in conf.py be kept

datatree has no _static directory, though xarray does. So I suppose we don't need it here.