py:obj reference target not found with sphinx 9.x

[jschueller]

sphinx 9.x has rewritten significantly its autodoc extension,
is there anything left to do in numpydoc to leverage the new api ?

I noticed the change when upgrading sphinx as I had to switch autodoc_use_legacy_class_based=True to use the legacy class-based API:
https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_use_legacy_class_based

else it gave me lots of warnings about references not found: [ref.obj] for stuff that should be filtered by :exclude-members: (nitpicky mode), eg:

/tmp/build/python/src/site-packages/persalys/persalys.py:docstring of persalys.persalys.Analysis:8: WARNING: py:obj reference target not found: thisown [ref.obj]

that I dont get otherwise without numpydoc

so is this a known task to handle the new default, or should I try to write a minimal reproducer ?

[larsoner]

I don't know of anyone looking into this so yes some minimal reproducer would be a good start!

[jschueller]

ok, I can reproduce with the (modified) tinybuild example, when numpydoc is enabled it yields a missing ref of an excluded attribute:

numpydoc_test_module.py:
class MyClass:
    """A class."""

    thisown = property(lambda x: True, lambda x, v: True, doc="The membership flag")

    def example(self, x):
        """Example method."""

index.rst:
.. autoclass:: MyClass
   :exclude-members: thisown

first install sphinx==9.1.0, numpydoc==1.10.0 then:

$ cd /tmp
$ git clone -b thisown --depth 1 https://github.com/jschueller/numpydoc.git
$ cd numpydoc/numpydoc/tests/tinybuild
$ make html
Running Sphinx v9.1.0
...
/tmp/numpydoc/numpydoc/tests/tinybuild/numpydoc_test_module.py:docstring of numpydoc_test_module.MyClass:8: WARNING: py:obj reference target not found: thisown [ref.obj]
...
build finished with problems, 1 warning (with warnings treated as errors).

now if you drop the numpydoc extension in conf.py the warning disappears, or downgrade sphinx to 8.x
it also goes away if you keep numpydoc but uncomment the autodoc_use_legacy_class_based=True line
be sure to call make clean between atempts

or use this archive:
tinybuild.zip

[jschueller]

hello @larsoner, any idea if the problem comes from numpydoc or sphinx here based on my minimal reproducer ?

[larsoner]

No I have not looked into it yet. Hopefully someone can find time at some point 😓

[jschueller]

figured it out in #688