classification
Title: Fix referencing of built-in types (list, int, ...)
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: benjamin.peterson, bsipocz, chris.jerdonek, docs@python, eric.araujo, ezio.melotti, frougon, georg.brandl, jonash, r.david.murray
Priority: normal Keywords: patch

Created on 2011-05-01 20:21 by jonash, last changed 2017-06-30 19:31 by python-dev.

Files
File name Uploaded Description Edit
p1.patch jonash, 2011-05-28 13:59 Fix int, str, float... markup types in 2.7 documentation
Pull Requests
URL Status Linked Edit
PR 2518 merged python-dev, 2017-06-30 18:52
PR 2520 merged python-dev, 2017-06-30 19:31
Messages (42)
msg134923 - (view) Author: Jonas H. (jonash) * Date: 2011-05-01 20:21
Intersphinx-ing of int, list, float, ... should work with ":class:`int`" (list, float, ...). Also, intersphinx-ing list methods, e.g. ":meth:`list.insert`", should work.
msg134952 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-05-02 07:06
See also #4966 and #11976.
msg134957 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-05-02 10:56
I changed the title: intersphinx is a Sphinx extension used to links to foreign documentation, not create links inside one doc (as I understand the request is).
msg134960 - (view) Author: Jonas H. (jonash) * Date: 2011-05-02 11:27
Actually I need to be able to intersphinx (because my documentation work is not the Python docs :-) but I guess it boils down to the same problem of incomplete Sphinx module/class indices.
msg134979 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2011-05-02 15:07
FWIW, :func:`int/float` work IIRC.
msg134985 - (view) Author: Jonas H. (jonash) * Date: 2011-05-02 15:35
Indeed they do; but documentation writers need to know that `int()` and `float()` are functions, which is counterintuitive. (and a CPython implementation detail)
msg134986 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2011-05-02 15:36
2011/5/2 Jonas H. <report@bugs.python.org>:
>
> Jonas H. <jonas@lophus.org> 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.
msg135320 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-05-06 16:39
> 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.
msg135334 - (view) Author: Jonas H. (jonash) * Date: 2011-05-06 17:11
> 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?
msg135345 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-05-06 17:37
str, list and friends are both functions and classes, if you want to go that way :)  Let’s keep purism out of this and discuss the result: we agree that missing links are a problem, so let’s fix it.

> 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.
msg135354 - (view) Author: Jonas H. (jonash) * Date: 2011-05-06 18:15
Shouldn't have used "decent" here, sorry. What I was trying to say is that there's no "reference-like" documentation for the list datatype (as for dict). There's more than enough quality documentation about lists but I think the way it's arranged can be improved.
msg137131 - (view) Author: Jonas H. (jonash) * Date: 2011-05-28 13:59
Does that look good to you? If it does, I'll go on using the script (http://paste.pocoo.org/show/396661/) on the 3.x docs.
msg137201 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-05-29 16:48
Again, changing the role :func: to :class: adds zero value to the tools or the human readers.  What’s needed are class *directives* that will provide a target for those links, e.g.:

.. class:: list

   .. method:: append

Then :func:`list` and :meth:`list.append` would generate links to his part of the docs.
msg137214 - (view) Author: Jonas H. (jonash) * Date: 2011-05-29 19:01
Linking a class using a function directive is counter-intuitive. That's why we need to make use of class directives rather than function directives here.
msg137243 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-05-30 05:22
You are confusing directives and roles.  As was already pointed out, there is currently no target for list.append to point to.  That's what needs to be added.
msg137254 - (view) Author: Jonas H. (jonash) * Date: 2011-05-30 10:38
I'm not.

My patch doesn't address the problem of unlinkable methods but wrong type declarations (read, wrong usage of ".. function::" directives) for builtins like int, float, bool, list etc. Because the directives change, the roles used to link to them (":func:`list`") have to be changed accordingly.  That's what this patch does.

I want to address `list` method documentation in the next step.
msg137264 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-05-30 13:26
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?
msg137268 - (view) Author: Jonas H. (jonash) * Date: 2011-05-30 13:31
> 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.
msg137271 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-05-30 13:37
> 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).
msg137272 - (view) Author: Jonas H. (jonash) * Date: 2011-05-30 13:39
What's wrong with the changes I propose with the patch, then? Sorry, I really don't get it, no matter how hard I try.
msg137273 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-05-30 13:51
Due to implementation details and history of CPython, it is not “more correct” to say that int is a function and a class.  You could argue either.  The question is however moot; 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.
msg137284 - (view) Author: Jonas H. (jonash) * Date: 2011-05-30 14:38
> 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? :-)
msg137290 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-05-30 15:12
It should certainly be reported to the sphinx tracker where the right people to make the decision for sphinx itself will see it.  Then if the decision is that type matters, python can decide how we want to handle that fact.  Since the core of sphinx does not care about type, I suspect this will be viewed as a bug in InterSphinx, but I could well be wrong.

Note that not using :func: does change the generated text.  With :func: you get () after the name, with :class: you don't.  So changing :func: to :class: for these is a decision that would need some discussion.

Also note that I'm guessing that there will be people who will object to expanding the description of the sequence types into full class/method docs.  So this, too, is a change that needs to be discussed with a wider audience.  I think I'm +0 on it myself; it makes the docs less concise and leads to redundant text, but it also make it easier to look up the method set of individual sequence types.
msg137312 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-05-30 17:37
Well (speaking as the Sphinx developer here), I view it as legacy behavior that type does not matter for non-intersphinx linking.

So the intersphinx behavior is the "correct" one, but we can't change the other now because of compatibility.

But (speaking as a Python doc person), I am -0 on changing :func: to :class: when we change these types to be documented as classes: it adds no value at all.
msg137321 - (view) Author: Jonas H. (jonash) * Date: 2011-05-30 19:27
> 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? :-)
msg137444 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-01 17:27
Jonas, I owe you an apology: when I abruptly asked “Could you make an effort to accept” etc., I had misread your message and thought you were asking to change the roles, but you were speaking of directives, so my comment was out of line.  Sorry.
msg137446 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-06-01 17:34
FWIW using the class directive also adds a 'class' before the name, and I -1 about having int()/float()/etc. prepended by 'class' in the functions.rst page.
What happens if we leave ".. function::" there and use ".. class::" in another page where all the methods are actually documented?
msg137447 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-01 17:37
Agreed.

I experimented with tuple and tuple.count and it turns out that it’s not easily solved: the count method is documented in the table describing all sequences methods, which should not be duplicated IMO; I tried adding a .. method:: tuple.append directive to create a link target, but that does not work in a table row.  Maybe the index directives can do what we want, but I do not understand them.
msg137459 - (view) Author: Jonas H. (jonash) * Date: 2011-06-01 21:10
> 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)?
msg137460 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-06-01 21:22
I think the only way to find it out is to try it and see.
In the worst case, sphinx will give an error while building the doc, if we are lucky it will just pick one of the two (or even better the one defined with the function directive while using :func:`` and the other one while using :class:``).
You can also experiment with :noindex: but I'm not sure it will do anything useful here.
msg137861 - (view) Author: Jonas H. (jonash) * Date: 2011-06-07 17:19
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...
msg137890 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-06-07 22:28
What if in the functions.rst page we specify the current module for all the functions (or even just for int/float/etc) as __builtin__ and use the function directive, and in the stdtypes.rst (or elsewhere) we use the class directive?
The idea is to pretend that '__builtin__.int' is a function in the __builtin__ module whereas 'int' is a global object.  In this way :func/class:`int` will probably link to the stdtypes.rst page, and :func/class:`~__builtin__.int` can be used to link to the functions.rst page (or the other way around if we want to link to the functions.rst page more often).  This is only a workaround though (assuming that it works), changing Sphinx to be smarter might be a better option.
msg137950 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-09 11:45
I don’t like the idea of built-in functions being displayed as “builtins.int”: normal use of builtins is without explicit use of the module name.
msg137985 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-06-09 15:22
Same here.
msg138007 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-06-09 16:27
It won't (because there's the ~ in :func/class:`~__builtin__.int`).  Specifying the module would just be a workaround used to distinguish the 'int' in functions.rst from the one in stdtypes.rst.
msg138084 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-10 15:41
When I said “I don’t like the idea of built-in functions being displayed as ‘builtins.int’”, I was thinking about the output of “.. function:: int” in combination with the module directive.  I don’t know if using currentmodule instead of module would be better.
msg138088 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-06-10 15:52
Why is any module directive needed anyway?
msg140781 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-07-21 05:08
To distinguish the 'int' in functions.rst from the one in stdtypes.rst (if it works...).
msg140839 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-21 23:50
Georg, could index directives be used to create link targets?  (see http://bugs.python.org/issue11975#msg137447)
msg140943 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-07-23 07:54
index does create targets, but they are not accessible for creating a link *to* it. They are only used for links from the indices.
msg215886 - (view) Author: Brigitta S (bsipocz) Date: 2014-04-10 14:47
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
msg215889 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-04-10 15:33
> 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 <list.append>`”.

For 2), 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.  For example, in https://docs.python.org/3/library/stdtypes.html#tuples after “Tuples implement all of the :ref:`common <typesseq-common>` sequence operations”, I’d add directives for tuple.index and tuple.count.


On a related note, it’s unfortunate that the global index has one entry for “tuple (built-in function)”, seven entries for “tuple object”, but none for “tuple.count” (and search doesn’t find it either) or “tuple class”.
History
Date User Action Args
2017-06-30 19:31:02python-devsetpull_requests: + pull_request2588
2017-06-30 18:52:44python-devsetpull_requests: + pull_request2587
2014-10-03 08:07:34frougonsetnosy: + frougon
2014-04-10 15:33:09eric.araujosetstage: patch review -> needs patch
messages: + msg215889
versions: + Python 3.5, - Python 3.2, Python 3.3
2014-04-10 14:47:24bsipoczsetnosy: + bsipocz
messages: + msg215886
2012-11-08 08:41:12ezio.melottisetnosy: + chris.jerdonek

type: enhancement
versions: + Python 3.4
2011-07-23 07:54:24georg.brandlsetmessages: + msg140943
2011-07-21 23:50:01eric.araujosetmessages: + msg140839
2011-07-21 05:08:31ezio.melottisetmessages: + msg140781
2011-06-10 15:52:38georg.brandlsetmessages: + msg138088
2011-06-10 15:41:01eric.araujosetmessages: + msg138084
2011-06-09 16:27:40ezio.melottisetmessages: + msg138007
2011-06-09 16:26:07georg.brandlunlinkissue12298 dependencies
2011-06-09 16:24:27ezio.melottilinkissue12298 dependencies
2011-06-09 15:22:38georg.brandlsetmessages: + msg137985
2011-06-09 11:45:01eric.araujosetmessages: + msg137950
2011-06-07 22:28:39ezio.melottisetmessages: + msg137890
2011-06-07 17:19:39jonashsetmessages: + msg137861
2011-06-01 21:22:33ezio.melottisetmessages: + msg137460
2011-06-01 21:10:58jonashsetmessages: + msg137459
2011-06-01 17:37:52eric.araujosetmessages: + msg137447
2011-06-01 17:34:57ezio.melottisetmessages: + msg137446
2011-06-01 17:27:28eric.araujosetmessages: + msg137444
2011-05-30 19:27:38jonashsetmessages: + msg137321
2011-05-30 17:37:38georg.brandlsetmessages: + msg137312
2011-05-30 15:12:04r.david.murraysetmessages: + msg137290
2011-05-30 14:38:40jonashsetmessages: + msg137284
2011-05-30 13:51:35eric.araujosetmessages: + msg137273
2011-05-30 13:39:27jonashsetmessages: + msg137272
2011-05-30 13:37:38eric.araujosetmessages: + msg137271
2011-05-30 13:31:51jonashsetmessages: + msg137268
2011-05-30 13:26:29eric.araujosetmessages: + msg137264
versions: - Python 3.1
2011-05-30 10:38:52jonashsetmessages: + msg137254
2011-05-30 05:22:21r.david.murraysetnosy: + r.david.murray
messages: + msg137243
2011-05-29 19:01:30jonashsetmessages: + msg137214
2011-05-29 16:48:50eric.araujosetmessages: + msg137201
2011-05-29 02:13:13ezio.melottisetnosy: + georg.brandl

stage: needs patch -> patch review
2011-05-28 13:59:28jonashsetfiles: + p1.patch
keywords: + patch
messages: + msg137131
2011-05-06 18:15:52jonashsetmessages: + msg135354
2011-05-06 17:37:40eric.araujosetmessages: + msg135345
2011-05-06 17:11:41jonashsetmessages: + msg135334
2011-05-06 16:39:07eric.araujosetmessages: + msg135320
2011-05-02 15:36:58benjamin.petersonsetmessages: + msg134986
2011-05-02 15:35:21jonashsetmessages: + msg134985
2011-05-02 15:07:08benjamin.petersonsetnosy: + benjamin.peterson
messages: + msg134979
2011-05-02 11:27:51jonashsetmessages: + msg134960
2011-05-02 10:56:19eric.araujosetnosy: + eric.araujo
title: Fix intersphinx-ing of built-in types (list, int, ...) -> Fix referencing of built-in types (list, int, ...)
messages: + msg134957

versions: + Python 3.1, Python 2.7, Python 3.2, Python 3.3
stage: needs patch
2011-05-02 07:06:08ezio.melottisetnosy: + ezio.melotti
messages: + msg134952
2011-05-01 20:31:47georg.brandllinkissue11976 superseder
2011-05-01 20:21:01jonashcreate