Ezio Melotti ezio.melotti@gmail.com added the comment:

See also #4966 and #11976.

---------- nosy: +ezio.melotti

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Jonas H. jonas@lophus.org added the comment:

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.

----------

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

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)

----------

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Éric Araujo merwok@netwok.org added the comment:

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 report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Éric Araujo merwok@netwok.org added the comment:

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.

----------

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Jonas H. jonas@lophus.org added the comment:

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.

---------- keywords: +patch Added file: http://bugs.python.org/file22164/p1.patch

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Éric Araujo merwok@netwok.org added the comment:

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.

----------

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

R. David Murray rdmurray@bitdance.com added the comment:

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.

---------- nosy: +r.david.murray

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Éric Araujo merwok@netwok.org added the comment:

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?

---------- versions: -Python 3.1

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Éric Araujo merwok@netwok.org added the comment:

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 report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Éric Araujo merwok@netwok.org added the comment:

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.

----------

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

R. David Murray rdmurray@bitdance.com added the comment:

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.

----------

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Jonas H. jonas@lophus.org added the comment:

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 report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Ezio Melotti ezio.melotti@gmail.com added the comment:

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?

----------

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Jonas H. jonas@lophus.org added the comment:

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 report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Jonas H. jonas@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@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Éric Araujo merwok@netwok.org added the comment:

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.

----------

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Ezio Melotti ezio.melotti@gmail.com added the comment:

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.

----------

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Georg Brandl georg@python.org added the comment:

Why is any module directive needed anyway?

----------

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Éric Araujo merwok@netwok.org added the comment:

Georg, could index directives be used to create link targets? (see http://bugs.python.org/issue11975#msg137447)

----------

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Changes by Ezio Melotti ezio.melotti@gmail.com:

---------- nosy: +chris.jerdonek type: -> enhancement versions: +Python 3.4

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

É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 <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”.

---------- stage: patch review -> needs patch versions: +Python 3.5 -Python 3.2, Python 3.3

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Changes by Roundup Robot devnull@psf.upfronthosting.co.za:

---------- pull_requests: +2587

_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue11975 _______________________________________

Kieran Siek kieransiek@protonmail.com added the comment:

7 years later I'd like to bring up essentially point #2 in this issue, which is the fact that additional list methods are :noindex: resulting in it being unlinked in the documentation.

Current state of affairs:

1. Common Sequence methods are documented at https://docs.python.org/3/library/stdtypes.html#common-sequence-operations, MutableSequence methods at https://docs.python.org/3/library/stdtypes.html#mutable-sequence-types.

2. Tuple methods do not have method directives and are just referred to the common sequence methods in the documentation text itself.

3. List methods have method directives with :noindex: at https://docs.python.org/3/tutorial/datastructures.html#more-on-lists

4. list.sort() has duplicate documentation at https://docs.python.org/3/library/stdtypes.html#list.sort, and the entry for list.sort() under 3) does not even link to the duplicate

It is pretty inconsistent and frankly confusing.

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 report@bugs.python.org https://bugs.python.org/issue11975 _______________________________________

Kieran Siek kieransiek@protonmail.com added the comment:

I don't disagree, just having linkable directives for lists and tuples would already make the documentation a lot more useful.

----------

_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue11975 _______________________________________