Issues with the generated intersphinx objects.inv

[altendky]

I'll take a look and see if I can provide a PR for this.

I have issues with Sphinx and linking to a few attrs docs. Specifically :mod:`attr` , :mod:`attrs` , :func:`attr.frozen` , and :func:`attr.mutable` . I used https://pypi.org/project/sphobjinv/ to extract https://www.attrs.org/en/stable/objects.inv and noticed an entire lack of any "role": "mod as well as the frozen and mutable being listed under attr.attr.

  "8": {
    "name": "attr.attr.frozen",
    "domain": "py",
    "role": "function",
    "priority": "1",
    "uri": "api.html#$",
    "dispname": "-"
  },
  "9": {
    "name": "attr.attr.mutable",
    "domain": "py",
    "role": "function",
    "priority": "1",
    "uri": "api.html#$",
    "dispname": "-"
  },

As an example, here's what sphobjinv shows for the dataclasses module.

  "3118": {
    "name": "dataclasses",
    "domain": "py",
    "role": "module",
    "priority": "0",
    "uri": "library/dataclasses.html#module-$",
    "dispname": "-"
  },

Perhaps created by this.

https://github.com/python/cpython/blame/4e605666b08b8f863cbbbdaa34bb06988e648d26/Doc/library/dataclasses.rst#L4

.. module:: dataclasses

Here are the seeming import paths for frozen and mutable.

attrs/src/attr/__init__.py

Lines 75 to 78 in 124c20c

	if sys.version_info[:2] >= (3, 6):
	from ._next_gen import define, field, frozen, mutable # noqa: F401
	__all__.extend(("define", "field", "frozen", "mutable"))

attrs/src/attr/_next_gen.py

Lines 122 to 123 in 124c20c

	mutable = define
	frozen = partial(define, frozen=True, on_setattr=None)

(with define() defined directly above)

I'm not quite sure what part of this would cause the doubled up attr.attr bit.

[altendky]

It seems that the attr.attr.frozen and attr.attr.mutable are caused by the use of .. function:: instead of .. autofunction:: in combination with the use of .. currentmodule:: attr at the top of the file.

https://github.com/python-attrs/attrs/blame/124c20cde0c7099494449e62f56781c8cb499570/docs/api.rst#L717-L730

.. autofunction:: attr.define
.. function:: attr.mutable(same_as_define)

   Alias for `attr.define`.

   .. versionadded:: 20.1.0

.. function:: attr.frozen(same_as_define)

   Behaves the same as `attr.define` but sets *frozen=True* and *on_setattr=None*.

   .. versionadded:: 20.1.0

.. autofunction:: attr.field

Note how frozen and mutable differ from their surrounding define and attr.field functions that use .. autofunction:: and do not exhibit the issue.

The .. function:: is used to avoid automatic generation of documentation for the signature etc since we want to just refer the user to look at the docs for define().

In #851 I have removed the attr. prefix to avoid the doubling up to attr.attr..

Expand for probably irrelevant diagnostic commentary

For the attr.attr.frozen and attr.attr.mutable there seems to be an interaction with the .. currentmodule:: attr and the use of attr despite this at .. function:: attr.frozen(same_as_define). Removing either the currentmodule call out or the attr. prefix alleviates the doubling up on attr.attr. in the inventory. I'll note that there are some items that do not specify the attr., thus leveraging the currentmodule specification, and others that do not. Also, attr.define for example does and does not exhibit the issue that frozen and mutable have. One of the special things about frozen and mutable relative to define is their definitions.

attrs/src/attr/_next_gen.py

Lines 122 to 123 in 124c20c

	mutable = define
	frozen = partial(define, frozen=True, on_setattr=None)

But... I tried commenting out frozen in attr/_next_gen.py as well as the import into attr/__init__.py and put a dummy def frozen(): print() into attr/__init__.py directly and it still suffered the same issue. Likewise for a similarly defined and located frozen2().

[altendky]

This issue confusingly yielded two PRs. #851 has been merged but #850 is still outstanding. Also, thanks!

[hynek]

Sorry and thanks. :)