[docs] [issue31024] typing.Tuple is class but is defined as data inside https://docs.python.org/3.6/objects.inv

[Bernát Gábor]

Bernát Gábor added the comment:

I suppose when the python.org documentation is generated the objects.inv file gets generated with it (I did not found exactly this piece of code here though). When Sphinx runs, it's intersphinx plugin goes out to python.org, downloads the objects.inv, decodes it, and then tries to map the docstring param/return values/references to URLs. 

Actually intersphinx does not make the deduction of the type. It uses what the users entered in the docstring. In this case the user needs to know for each element to which bucket has been assigned to (e.g. class/data/function/method/exception/macro); and for compatibility reason that needs to stay stable, otherwise with a Python upgrade the user would need to update the code of its docstrings.

That being said for the sake of automation, in my case there actually another sphinx plugin (https://github.com/agronholm/sphinx-autodoc-typehints/blob/master/sphinx_autodoc_typehints.py) which actually generates, on the fly, the type information. So I suppose as a fix for my problem the sphinx_autodoc_typehint could be altered to still give back data, even though this now is a class. I'm not sure though how confident I am on "lying" to users about the data/class; but I suppose it's a necessary evil at this point.

So should we keep everything as it is? When I first identified why Tuple does not have the URL mapped to it, I thought the problem to be the fact that it goes to the wrong bucket (by just inspecting its type): data; but now I see that may not be such a bad thing after all.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue31024>
_______________________________________