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

[Raymond Hettinger]

Raymond Hettinger  added the comment:

> 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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Kieran Siek]

Kieran Siek  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Éric Araujo  added the comment:

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

--
versions:  -Python 2.7, Python 3.11, Python 3.4, Python 3.5, Python 3.6, Python 
3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Kieran Siek]

Kieran Siek  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Roundup Robot]

Changes by Roundup Robot :


--
pull_requests: +2588

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Roundup Robot]

Changes by Roundup Robot :


--
pull_requests: +2587

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Florent Rougon]

Changes by Florent Rougon frou...@users.sourceforge.net:


--
nosy: +frougon

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Brigitta S]

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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

É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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ezio Melotti]

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


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

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Georg Brandl]

Georg Brandl ge...@python.org added the comment:

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

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

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

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

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ezio Melotti]

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

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

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

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

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Georg Brandl]

Georg Brandl ge...@python.org added the comment:

Why is any module directive needed anyway?

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Éric Araujo mer...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Georg Brandl]

Georg Brandl ge...@python.org added the comment:

Same here.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ezio Melotti]

Ezio Melotti ezio.melo...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Jonas H.]

Jonas H. jo...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ezio Melotti]

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

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

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

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ezio Melotti]

Ezio Melotti ezio.melo...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

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

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Jonas H.]

Jonas H. jo...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ezio Melotti]

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

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Jonas H.]

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

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Éric Araujo mer...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Jonas H.]

Jonas H. jo...@lophus.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?

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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Éric Araujo mer...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Jonas H.]

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

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Éric Araujo mer...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Jonas H.]

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

 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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[R. David Murray]

R. David Murray rdmur...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Georg Brandl]

Georg Brandl ge...@python.org added the comment:

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Jonas H.]

Jonas H. jo...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Éric Araujo mer...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Jonas H.]

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

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[R. David Murray]

R. David Murray rdmur...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Jonas H.]

Jonas H. jo...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ezio Melotti]

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


--
nosy: +georg.brandl
stage: needs patch - patch review

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Éric Araujo mer...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Jonas H.]

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

 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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Éric Araujo mer...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Jonas H.]

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

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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

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

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

--
nosy: +eric.araujo
stage:  - needs patch
title: Fix intersphinx-ing of built-in types (list, int, ...) - Fix 
referencing of built-in types (list, int, ...)
versions: +Python 2.7, Python 3.1, Python 3.2, Python 3.3

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Jonas H.]

Jonas H. jo...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Benjamin Peterson]

Benjamin Peterson benja...@python.org added the comment:

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

--
nosy: +benjamin.peterson

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Jonas H.]

Jonas H. jo...@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 rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Benjamin Peterson]

Benjamin Peterson benja...@python.org added the comment:

2011/5/2 Jonas H. rep...@bugs.python.org:

 Jonas H. jo...@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.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11975
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com