[docs] [issue11975] Fix referencing of built-in types (list, int, ...)

[Jonas H.]

Jonas H. <jonas at lophus.org> added the comment:

Having one page with two objects of the same name, e.g.

  .. function:: foo

  .. class:: foo

renders to two entries with the same anchor name (#foo). The first entry gets a link-to-this-paragraph marker, the second one doesn't.

Internal references (from within the same document) always link to the first entry because they use #foo anchor. (So if you put the class directive first, all links go to the class anchor.)

The first external reference (using intersphinx) always goes to the first target document element - no matter which type both have. The second reference isn't turned into a hyperlink.

This behaviour seems consistent with how HTML anchors work.

Having the two objects on two different pages however shows slightly odd results. Say we have this code on page 1:

  .. class:: foo

  :class:`foo`
  :func:`foo`

and

  .. function:: foo

on page 2, then both links in page 1 go to the page 1 'foo' (the class). However if you change order (putting the func role before the class role), those links go to the page 2 'foo' (the function).

All intersphinx-ed links go to the object on page 1, no matter the role order on page 1 or the external page.


I think we can conclude that using class and function directives at the same time doesn't help very much...

----------

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