Bernát Gábor added the comment: so here's the problem in detail:
Intersphinx (http://www.sphinx-doc.org/en/stable/ext/intersphinx.html) is a built in Sphinx plugin that allows to link to documentation of other projects in your own documentation. For example when specifying the argument of a function which can be either int or string you might specify the argument to be Union[int, str]. In this case Sphinx will generate the type of the argument as this object, where e.g. the Union word will be a link to https://docs.python.org/3/library/typing.html#typing.Union and so on. In order to know for which object/function/type what is the correct URL an intersphinx object (which is basically a mapping) needs to be generated. This maps each element to an URL. This intersphinx mapping storage object (available at https://docs.python.org/3/objects.inv and similarly under other version pattern for the according version) is generated from the Python documentation. Now there's one indirection as far as this objects.inv goes; it does not actually stores mappings of element to URL, but what instead does it stores a mapping of type to element to url. Where type is here defined as either data/class etc. In order to resolve from an element to an URL both keys need to be correct (the type and the key too). For Python 3.6+ the typing.Tuple mapping now fails because according to the documentation the Tuple is under the section data, but once intersphinx looks at the Tuple during documentation generation it deduces it actually is of type class, and tries to locate it there. In order for intersphinx to resolve the correct web page URL, the runtime information of an element need to coincide with it's documentation type. Hence, what this PR tries to fix, migrating the documentation type/section of data to class (as in the meantime under Python 3.6 the Tuple is now a class). For the end user the fact that this is a class is still hidden, but for the documentation generation tool to resolve the correct URL, the runtime information needs to coincide with the documentation one. We should probably add a unit test that makes sure all runtime "type" matches with documentation "type" in the future. Let's make that the scope of another PR; is now clear? ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue31024> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
