Configure intersphinx

[lochhh]

Description

What is this PR

• [ ] Bug fix
• [x] Addition of a new feature
• [ ] Other

Why is this PR needed? This PR configures intersphinx for linking external Python packages.

What does this PR do? This PR

• configures intersphinx mappings to allow automatic linking of external Python packages
• adds custom CSS to decorate (underline) hyperlinks for movement-only modules in the sphinx gallery examples. This prevents excessive underlined hyperlinks from showing (see also related issues in sphinx-gallery and scikit-learn). The other alternative is to completely disable hyperlinks using "inspect_global_variables" : False in sphinx_gallery_conf, but I thought it is nicer to have the hyperlink show "onmouseover" events
• adds instructions for cross-referencing Python object in the contributing guide
• adds sphinx docs to the MyST URL schemes
• uses the simpler :role:`target` syntax for cross-referencing in the API reference and examples

How has this PR been tested?

Docs built locally and in CI

Does this PR require an update to the documentation?

Relevant instructions have been added to the contributing guide.

Checklist:

• [x] The code has been tested locally
• [ ] Tests have been added to cover all new functionality
• [x] The documentation has been updated to reflect any changes
• [x] The code has been formatted with pre-commit

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 99.76%. Comparing base (0cfded5) to head (26eb75d).

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #269 +/- ## ======================================= Coverage 99.76% 99.76% ======================================= Files 14 14 Lines 866 866 ======================================= Hits 864 864 Misses 2 2 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[lochhh]

• I didn't know about the <project: and <inv: syntax for referencing. It's cool to know but I wonder if we should skip mentioning these alternatives. My reasoning is that the other .md syntax mirrors more closely the .rst syntax, and is thus easier to memorise (at least for me). Plus, having all cross-references follow analogous syntax will improve the readability of the docs source files.

Agreed. Will remove those!

• For external references, I was (perhaps mistakenly) using {class} or {meth}. Do you know what's the advantage of having external: ahead of them? Should we convert all my existing external references to that syntax (so that existing code matches our guidelines)? Most people will just copy the syntax of existing references rather than reading the contributing guide.

All of the below are correct:

• {meth}`xarray.Dataset.update`: default py: is assumed
• {py:meth}`xarray.Dataset.update`: explicit about language (perhaps not necessary if we don't reference objects written in other languages), will first look for matching target in movement doc set, if not found, look up intersphinx_mapping for external projects
• {external:meth}`xarray.Dataset.update`: directly look up intersphinx_mapping for external projects

With external: we can also reference other external Sphinx doc pages, e.g.

{external:doc}`user-guide/terminology` 

will generate the link to xarray Terminology vs. what we currently use, i.e. myst_url_schemes:

[terminology](xarray:user-guide/terminology.html)

Another example linking to the definition of "Concatenating":

{external:std:term}`Concatenating` 

vs.

[Concatenating](xarray:user-guide/terminology.html#term-Concatenating) 

More on external: here.

Is external: overcomplicating things? Shall we just keep the simpler {meth}`xarray.Dataset.update` syntax, which works, for referencing Python objects; and continue using myst_url_schemes for referencing other non-API pages?

[niksirbi]

Is external: overcomplicating things? Shall we just keep the simpler {meth}`xarray.Dataset.update` syntax, which works, for referencing Python objects; and continue using myst_url_schemes for referencing other non-API pages?

I think so. The examples you mentioned (e.g. referencing specific doc pages or terms) are indeed very neat, but we already use myst_url_schemes for that, which seems to me like the more general solution as it works for any webpages, not just for sphinx docs pages.

[lochhh]

Since we now decide for the simpler :role:`target` syntax (that implicitly assumes the domain name is py), I've updated all references to use this. As the instructions for internal vs external referencing have overlaps, I'm only providing examples in external referencing, whilst pointing readers to the internal referencing section.

[sonarcloud[bot]]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud

[niksirbi]

Since we now decide for the simpler :role:`target` syntax (that implicitly assumes the domain name is py), I've updated all references to use this. As the instructions for internal vs external referencing have overlaps, I'm only providing examples in external referencing, whilst pointing readers to the internal referencing section.

I'm happy with this, 👍🏼 for uniformity and consistency. Ready to merge from my point-of-view. Thanks for putting order into this mess (of mostly my creation).