This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Missing `list` symbols in the object inventory
Type: Stage:
Components: Documentation Versions: Python 3.11
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Akarys, docs@python, eric.araujo, ezio.melotti, mdk, willingc
Priority: normal Keywords:

Created on 2021-11-09 08:18 by Akarys, last changed 2022-04-11 14:59 by admin.

Messages (2)
msg406004 - (view) Author: Matteo Bertucci (Akarys) * Date: 2021-11-09 08:18
Sphinx generates a quite useful inventory file, listing all the different symbols available inside the documentation. You can find the docs.python.org inventory over at https://docs.python.org/objects.inv. The syntax of this file can be found here https://sphobjinv.readthedocs.io/en/latest/syntax.html.

We use it over at Python Discord to power up our `!docs` command. It allows us to look up symbols such as `asyncio.run`, have nicely formatted documentation and links to the web page. 

The problem is due to where the `list` method documentations are located, inside `/tutorial/datastructures` (https://docs.python.org/3/tutorial/datastructures.html), no symbol is exported for those, making commands such as `!docs list.append` fail, which is quite a bummer. It would be very nice to have access to those.
msg406289 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2021-11-13 19:55
If you search in the index, there is no entry like 'append (list method)', only 'append (sequence method)': https://docs.python.org/3/genindex-A.html
This goes to the reference docs, where list methods are documented indirectly by reference to the Sequence protocol described just above the list section: https://docs.python.org/3/library/stdtypes.html#lists

The tutorial page lists all methods for people learning, with noindex markup to avoid pointing from the index to the reference: https://github.com/python/cpython/blob/3.10/Doc/tutorial/datastructures.rst#L19

The individual decisions make sense, but I think the results is not satisfactory: there is no reference to list.append (etc) in the index or the sphinx inventory (only 'list.sort' is there, from the entry in the library/stdtypes list section).  I think index markup should be added for all built-in types in the stdtypes page so that links are generated.  Alternatively, add a sphinx directive to register that a type matches the sequence (etc) protocol, so that index entries for all protocol methods can be generated automatically.
History
Date User Action Args
2022-04-11 14:59:52adminsetgithub: 89923
2021-11-13 19:55:47eric.araujosetmessages: + msg406289
2021-11-12 21:53:17terry.reedysetnosy: + ezio.melotti, eric.araujo, willingc, mdk

versions: - Python 3.6, Python 3.7, Python 3.8, Python 3.9, Python 3.10
2021-11-09 08:18:16Akaryscreate