Author kosayoda
Recipients benjamin.peterson, bsipocz, chris.jerdonek, docs@python, eric.araujo, ezio.melotti, frougon, georg.brandl, jonash, kosayoda, r.david.murray
Date 2021-04-28.14:15:41
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1619619342.22.0.209614658376.issue11975@roundup.psfhosted.org>
In-reply-to
Content
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.
History
Date User Action Args
2021-04-28 14:15:42kosayodasetrecipients: + kosayoda, georg.brandl, frougon, benjamin.peterson, ezio.melotti, eric.araujo, r.david.murray, jonash, chris.jerdonek, docs@python, bsipocz
2021-04-28 14:15:42kosayodasetmessageid: <1619619342.22.0.209614658376.issue11975@roundup.psfhosted.org>
2021-04-28 14:15:42kosayodalinkissue11975 messages
2021-04-28 14:15:41kosayodacreate