Add cross-links to API docstring from tutorial and user-guide

[amanbagrecha]

• Partially Addresses "Deep linking" disparate documentation resources together #8008
• Tests added
• User visible changes (including notable bug fixes) are documented in whats-new.rst
• New functions/methods are listed in api.rst

Cross links for

• apply_ufunc
• weighted
• indexing
• interp
• map_blocks
• groupby
• coarsen

[welcome]

Thank you for opening this pull request! It may take us a few days to respond here, so thank you for being patient.
If you have questions, some answers may be found in our contributing guidelines.

[dcherian]

Thanks @amanbagrecha . I changed the links to more general pages.

[amanbagrecha]

Thanks @dcherian for the edits. I reverted the docs you made for apply_ufunc to the correct url. Also added additional cross-links to user-guide and tutorials. I have few questions

• Shall I add as many cross-links for the API to user-guide and tutorial in the same PR?
• Currently I am using absolute URL for user-guide links, for eg: https://github.com/pydata/xarray/pull/8311/files#diff-386f35dda14ca12d315f2eb71f0ab35d7fdc73419b5dc5175ea5720f3206903bR6953-R6954, is there a better way to it, do avoid breakage in the future?

[keewis]

I wonder if we should be using the intersphinx entries in https://tutorial.xarray.dev/objects.inv?

If so, you'd need to add

    "xarray-tutorial": ("https://tutorial.xarray.dev/", None),

to intersphinx_mapping

[keewis]

you can use sphobjinv su -u https://docs.xarray.dev/en/latest computation to find the appropriate link, in this case

:std:label:`/user-guide/computation.rst#weighted-array-reductions`

(though maybe we need to add label directives to user-guide/computation to make this easier? E.g. add

.. _weighted-array-reductions:

just before that section... not sure if - is a allowed character in labels, though)

[amanbagrecha]

many thanks! I made the necessary changes.

[amanbagrecha]

I wonder if we should be using the intersphinx entries in https://tutorial.xarray.dev/objects.inv?

If so, you'd need to add

    "xarray-tutorial": ("https://tutorial.xarray.dev/", None),

to intersphinx_mapping

I added xarray-tutorial to intersphinx_mapping. Though I am confused how to use it. I tried sphobjinv su -u https://tutorial.xarray.dev/ fundamentals and found the necessary link, though unable to reference it correctly.
I tried the following to no avail. How do I resolve this?

:doc:`fundamentals/03.4_weighted`

[keewis]

not sure, you might have to use a prefix:

:doc:`xarray-tutorial:fundamentals/03.4_weighted`

where the prefix is the value you put as the dict key in intersphinx_mapping

[amanbagrecha]

not sure, you might have to use a prefix:

:doc:`xarray-tutorial:fundamentals/03.4_weighted`

where the prefix is the value you put as the dict key in intersphinx_mapping

Thanks this worked. Now I'm struggling to find a way to link just the section as in https://tutorial.xarray.dev/intermediate/01-high-level-computation-patterns.html#label-space-windows-or-bins-groupby. Since tutorials are in markdown, I cannot add a directive I think.

[keewis]

I think this should be possible (not sure though, especially given jupyter-book/jupyter-book#1767), but might need changes to the tutorial. @dcherian, any ideas?

[dcherian]

No ideas but this is a major improvement. So let's just go ahead with a link to the whole page.

[keewis]

was there anything else you'd like to change, @amanbagrecha? Otherwise I think we can undo the nbsphinx error setting change and merge.

[keewis]

we might have to revisit the links once xarray-tutorial has section targets, but for now this looks good to me. Thanks a lot, @amanbagrecha

[dcherian]

:( This seems to have messed up some formatting though:

while on main

[keewis]

this should be valid, though. So we might need to fix napoleon to allow this.

[keewis]

it appears we had a similar issue more than two years ago when we first introduced :doc: links to See Also (see #5176), where we concluded that this is a bug in napoleon (nobody got around to reporting / fixing that since then, though).

[dcherian]

OK well this is an improvement in any case. Merging.

[dcherian]

Thanks @amanbagrecha this is a great contribution. Welcome to Xarray!

[welcome]

Congratulations on completing your first pull request! Welcome to Xarray! We are proud of you, and hope to see you again!