Author eric.araujo
Recipients benjamin.peterson, bsipocz, chris.jerdonek, docs@python, eric.araujo, ezio.melotti, georg.brandl, jonash, r.david.murray
Date 2014-04-10.15:33:08
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1397143989.17.0.937704131133.issue11975@psf.upfronthosting.co.za>
In-reply-to
Content
> 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
2014-04-10 15:33:09eric.araujosetrecipients: + eric.araujo, georg.brandl, benjamin.peterson, ezio.melotti, r.david.murray, jonash, chris.jerdonek, docs@python, bsipocz
2014-04-10 15:33:09eric.araujosetmessageid: <1397143989.17.0.937704131133.issue11975@psf.upfronthosting.co.za>
2014-04-10 15:33:09eric.araujolinkissue11975 messages
2014-04-10 15:33:08eric.araujocreate