Implement equivalent of autosummary's currentmodule behavior for interlinks

[machow]

sphinx's default template uses the directive ::currentmodule set to whatever module corresponds to the piece being documented (e.g. plotnine.geoms.geom_col sets plotnine.geoms). This allows docstrings to do references like :class:geom_bar, which refer to :class:plotnine.geoms.geom_bar.

We need to figure out a way to enable this behavior in the interlinks extension.

edit: here's an example of sphinx using ::currentmodule

Builder
---------

.. currentmodule:: quartodoc

.. autoclass:: Builder
   .. automethod:: __init__

[machow]

@has2k1 makes a good point that--as a package author--he's likely to make way more internal links, so we should prioritize solving internal links w/o necessarily needing the interlinks extension (which could always require fully qualified names).

This would require parsing links inside the renderer, though, but worth thinking through.

I'll reach out to Carlos to see if we can pair on options for this issue

[machow]

Looking around, there are two ways I've seen packages handle shorthand crossrefs for package specific objects.

pandas

pandas uses a header, that is inserted via templating into basically all doc pages. It looks like this:

header = f"""\
.. currentmodule:: pandas

.. ipython:: python
   :suppress:

   import numpy as np
   import pandas as pd

   np.random.seed(123456)
   np.set_printoptions(precision=4, suppress=True)
   pd.options.display.max_rows = 15

   import os
   os.chdir(r'{os.path.dirname(os.path.dirname(__file__))}')
"""

Notice that ..currentmodule:: pandas allows the page to crossreference directly to pandas objects, e.g. DataFrame, rather than pandas.DataFrame.

sqlalchemy

sqlalchemy uses a custom extension, that lets it specify shorthands for modules. For example, _sa to stand for sqlalchemy.

[has2k1]

1. To do something similar to ..currentmodule:: pandas you may be able to do it with a quarto shortcode. e.g. {{< currentmodule pandas }}>. There may be some complications though.

2. When I did the interlinking for numpydoc, I implemented something similar what sqlalchemy has. Instead of prefixes, complete aliases.

[machow]

Ah, thanks for the pointer to numpydoc (and nudge at shortcodes)!

For the numpy xref config, does this only apply to crossrefs in docstrings? I'm trying to get a handle on all the ways people crossway in sphinx, so it's really helpful to see.