[issue11975] Fix intersphinx-ing of built-in types (list, int, ...)
New submission from Jonas H.
Ezio Melotti
Éric Araujo
Jonas H.
Benjamin Peterson
Jonas H.
Benjamin Peterson
Jonas H.
added the comment: Indeed they do; but documentation writers need to know that `int()` and `float()` are functions, which is counterintuitive. (and a CPython implementation detail)
They're not even functions, just documented as such.
----------
_______________________________________
Python tracker
Éric Araujo
Intersphinx-ing of int, list, float, ... should work with ":class:`int`" (list, float, ...).
Is this a problem in our markup or a bug in intersphinx? IIRC, you can use func, class, mod, method or what you want, all these roles look up objects in the same way.
Also, intersphinx-ing list methods, e.g. ":meth:`list.insert`", should work.
If this work within one documentation set (as I believe it does) but not with intersphinx, it’s an intersphinx bug which should be reported to the Sphinx bug tracker on bitbucket.
----------
_______________________________________
Python tracker
Jonas H.
Is this a problem in our markup or a bug in intersphinx?
It's a markup problem -- those types are documented as functions, using the :func: role/`.. func::` directive. It's not only a markup mismatch but, strictly speaking, it's *wrong* documentation: str, int, ... aren't functions, they're *classes* and should be documented as such. It's a bit odd to search for information on the str *class* in the list of built-in *functions*.
If this work within one documentation set (as I believe it does)
It does not. For example, in http://docs.python.org/library/functions.html#max there's a reference to list.sort using :meth:`list.sort` but no link could be generated. How could it possibly work without decent documentation about the list data type?
----------
_______________________________________
Python tracker
Éric Araujo
How could it possibly work What’s missing is class and method directives. If you’re interested in submitting a patch, guidelines are found at http://docs.python.org/dev/documenting/markup#information-units and http://docs.python.org/devguide
without decent documentation about the list data type? I can understand your feelings, but such a comment is a bit harsh for all the volunteer time that’s been put into documenting Python. http://docs.python.org/dev/library/functions#list and http://docs.python.org/dev/library/stdtypes#typesseq seem quite “decent” to me.
----------
_______________________________________
Python tracker
Jonas H.
Jonas H.
Changes by Ezio Melotti
Éric Araujo
Jonas H.
R. David Murray
Jonas H.
Éric Araujo
Jonas H.
Could you make an effort to accept our word that using :class: instead of :func: would bring zero value to the indexing system nor to human readers?
I'm already doing; but I don't see anyone having made a good point against my preference of using ".. class::" to document classes.
----------
_______________________________________
Python tracker
Éric Araujo
I'm already doing; Thanks.
but I don't see anyone having made a good point against my preference of using ".. class::" to document classes. We have agreed it is needed (I think it’s on another bug report, maybe a duplicate).
----------
_______________________________________
Python tracker
Jonas H.
Éric Araujo
Jonas H.
when you mark up something with a mod, func, class or meth role, Sphinx will find the target without paying attention to its type. So changing :func: to :class: does not bring anything.
From a quick test this seems to hold true for links within one project but not for Sphinx' intersphinx extension, which actually cares about types.
So the question is whether we keep CPython implementation details (many builtins being both a class and a function) out of the documentation or we get the Sphinx developers to change intersphinx behaviour. I guess you'd suggest the latter, right? :-)
----------
_______________________________________
Python tracker
R. David Murray
Georg Brandl
Jonas H.
So the intersphinx behavior is the "correct" one, but we can't change the other now because of compatibility.
Could you be convinced to use that legacy behaviour for intersphinx, too? :-)
----------
_______________________________________
Python tracker
Éric Araujo
Ezio Melotti
Éric Araujo
Jonas H.
Jonas, I owe you an apology [...]
Thanks Éric, I got a bit worried about getting on your nerves...
Based on Ezio's idea: What happens if we have both a ".. function:: foo" and ".. class:: foo" -- where do :func:`foo` and :class:`foo` link to (internally and using intersphinx)?
----------
_______________________________________
Python tracker
Ezio Melotti
Jonas H.
Ezio Melotti
Éric Araujo
Georg Brandl
Ezio Melotti
Éric Araujo
Georg Brandl
Ezio Melotti
Éric Araujo
Georg Brandl
Changes by Ezio Melotti
Brigitta S added the comment:
I would like to reference the list methods in a documentation using intersphinx-ing e.g ":meth:`list.append`" etc. However there are no links generated for these.
I may underestimate issues raised in this thread, but it naively seems that removing the :noindex: lines from datastructures.rst would solve the problem.
thanks
----------
nosy: +bsipocz
_______________________________________
Python tracker
Éric Araujo added the comment:
I may underestimate issues raised in this thread
I re-read the discussion, these are the two main issues:
1) We’d like list/tuple/etc. documented in two different pages (as functions and as types), which causes issues when Sphinx builds its index of referenceable objects, as investigated by Jonas.
2) We’d like to have link targets for list.count/tuple.count/etc. but the existing doc has one place only to document all sequence types’ count method, so the fix is not simple.
For 1), I now think that Ezio’s builtins.list/list hack could be a good idea, as long as “list” (i.e. not “builtins.list”) is always displayed in the text for humans (I don’t care about URIs or rst source), and that people using intersphinx can write “:meth:`list.append`” and don’t have to go with “:meth:`builtins.list.append
Changes by Florent Rougon
Changes by Roundup Robot
Changes by Roundup Robot
Kieran Siek
I would be fine with adding mostly empty method directives to make links work, without duplicating the info in the existing “common sequence operations” table and footnotes.
Eric mentions this, but then the situation would either be:
1. Tuple methods link to common sequence methods, list methods link to the More on Lists version of the Data Structures tutorial
or
2. Tuple methods and list methods both link to common sequence methods, and ??? to the More on Lists version
which is still inconsistent.
Another solution would be to move list method documentation to under the list class (where the duplicate list.sort() is), but in this case the tutorial would be affected as well.
I don't see a clear solution here, but I think it's very worth rethinking.
----------
nosy: +kosayoda
versions: +Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9
_______________________________________
Python tracker
Éric Araujo
Kieran Siek
Raymond Hettinger
I don't see a clear solution here, but I think it's very worth rethinking.
If you come up with a clear improvement for adding link targets, please open it in a separate tracker issue. The other proposals in this thread have all been mostly voted down.
----------
nosy: +rhettinger
resolution: -> rejected
stage: needs patch -> resolved
status: open -> closed
_______________________________________
Python tracker
participants (11)
-
Benjamin Peterson
-
Brigitta S
-
Ezio Melotti
-
Florent Rougon
-
Georg Brandl
-
Jonas H.
-
Kieran Siek
-
R. David Murray
-
Raymond Hettinger
-
Roundup Robot
-
Éric Araujo