Doc build error

[TomNicholas]

Weird failure kept happening in the CI in #279

https://readthedocs.org/projects/xarray-datatree/builds/22664223/

Somehow xarray's fault??

ValueError: Error parsing See Also entry ':doc:`xarray-tutorial:intermediate/indexing/indexing`' in the docstring of isel in /home/docs/checkouts/readthedocs.org/user_builds/xarray-datatree/checkouts/279/datatree/mapping.py.

[keewis]

adding xarray-tutorial to the intersphinx mapping might help? I'm guessing it doesn't like the unknown link prefix?

[etienneschalk]

Hello,

I tried to add xarray-tutorial in the intersphinx_mapping, as such:

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),
   "xarray-tutorial": ("https://tutorial.xarray.dev/", None),
}

However, the error on make build is (whether the xarray-tutorial entry has been added) still:

Extension error (numpydoc.numpydoc):
Handler <function mangle_signature at 0x7fb8f444cdc0> for event 'autodoc-process-signature' threw an exception (exception: Error parsing See Also entry ':doc:`xarray-tutorial:intermediate/indexing/indexing`' in the docstring of isel in /home/user/dev/datatree/datatree/mapping.py.)
make: *** [Makefile:54: html] Error 2

[TomNicholas]

@keewis I need to release datatree (to fix #293), but do you know whether that would cause problems (to release when the docs build on main is not working?

EDIT: I also tried adding xarray-tutorial in the intersphinx_mapping just to double-check - that didn't work for me either.

[keewis]

revisiting this, I think the reason this fails while xarray's docs build fine is that xarray uses napoleon while datatree uses numpydoc. Since the merge will combine both anyways, it might be worth switching datatree to use napoleon?

[keewis]

should we cut a release, now that the docs build again?