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.

See also bpo-4966 and bpo-11976.

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).

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.

FWIW, :func:`int/float` work IIRC.

Indeed they do; but documentation writers need to know that int() and float() are functions, which is counterintuitive. (and a CPython implementation detail)

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.

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.

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?

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.

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.

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.

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.

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.

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.

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.

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?

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.

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).

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.

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.

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? :-)

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.

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.

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? :-)

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.

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?

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.

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)?

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.

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

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.

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.

Same here.

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.

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.

Why is any module directive needed anyway?

To distinguish the 'int' in functions.rst from the one in stdtypes.rst (if it works...).

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

index does create targets, but they are not accessible for creating a link *to* it. They are only used for links from the indices.

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

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

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.

I don’t think consistency should be the main goal, but usefulness.

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

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.