Intershpinx :mod:attrs no longer resolves

[inducer]

As of attrs 22.2.0, the intersphinx reference

:mod:`attrs`

no longer resolves.

Sample failed CI downstream CI run:
https://github.com/inducer/pytato/actions/runs/3774274601/jobs/6416277949

[webknjaz]

Confirmed that no module objects are exposed: https://webknjaz.github.io/intersphinx-untangled/www.attrs.org/.

[webknjaz]

Sample failed CI downstream CI run:
inducer/pytato/actions/runs/3774274601/jobs/6416277949

Here's the relevant part of that log:

/home/runner/work/pytato/pytato/doc/design.rst:234: WARNING: py:mod reference target not found: attrs
/home/runner/work/pytato/pytato/doc/design.rst:237: WARNING: py:mod reference target not found: attrs
/home/runner/work/pytato/pytato/doc/design.rst:244: WARNING: py:mod reference target not found: attrs
[...]
build finished with problems, 3 warnings.
make: *** [Makefile:20: html] Error 1
Error: Process completed with exit code 2.

[webknjaz]

@inducer Here's alternatives for you to use @ https://github.com/inducer/pytato/blob/[5aee209](https://github.com/inducer/pytato/commit/5aee209cb47089e72b81287559a654aef0592db9)/doc/design.rst#dataclasses--modattrs:

:doc:`attrs <attrs:index>`

:doc:`attrs <attrs:overview>`

:doc:`attrs <attrs:api>`

:doc:`attrs <attrs:why>`

Provided that you fix your https://github.com/inducer/pytato/blob/5aee209/doc/conf.py#L17-L32 to use modern syntax with a mapping with attrs as a key for the corresponding intersphinx link.

[webknjaz]

This patch is at fault: 15230d9 (#1067).

cc @hynek dunno if this was intentional, but I'd treat intersphinx objects as public API.

P.S. @inducer it is possible to cache the object.inv files right in your repo making your builds more predictable.

[hynek]

Yeah this was not on purpose, so sorry for the breakage.

I've fixed and while looking at it, noticed there's some mangled names like attr.attr.cmp_using sigh.

Is the untangling link supposed to update somehow?

[webknjaz]

I've fixed and while looking at it, noticed there's some mangled names like attr.attr.cmp_using sigh.

Is the untangling link supposed to update somehow?

@hynek I see that api.rst has .. currentmodule:: attr — this is what is prepended to all the definitions in that document. So the reference created by .. autofunction:: attrs.cmp_using becomes

:py:func:`attr.attr.cmp_using`

I suppose that you may want to decide how you want things to be documented and either drop the explicit prefixes or remove the current module directive. I think there's a setting in Sphinx controlling how your API definitions are displayed, too.

P.S. I noticed that there's both .. autofunction:: attrs.cmp_using and .. function:: attr.cmp_using. I think this is redundant.

[webknjaz]

Another useful setting is :canonical: — https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-option-py-function-canonical. See also add_module_names: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-add_module_names.

[webknjaz]

Tracking issue backreference: #1077.

[hynek]

P.S. I noticed that there's both .. autofunction:: attrs.cmp_using and .. function:: attr.cmp_using. I think this is redundant.

I suspect that sphinx is just being smart if it knows the symbol name (autofunction) vs not.

[webknjaz]

@hynek but wasn't it you who added both lines?

[hynek]

I'm somewhat confused by the question in this context. For posterity: I've added both such that people can refer to :mod:`attr` and :mod:`attrs` as OP wanted.

I'm currently splitting the file up in #1080, though.

[webknjaz]

@hynek oh, I was referring to the fact that there's both function and autofunction for the same target.