Docs: Built-in Functions: Make missing functions appear in side nav

[dcki]

On the left side of https://docs.python.org/3/library/functions.html there is a gray side nav with a title at the top that says "Table of Contents". In that side nav there are many links to sections of that same page, but I noticed that there is no link to list() even though there is an entry for list() in the page.

This PR fixes that problem, but causes other problems. I don't know what the best solution is.

When I looked at the entry for list() in Doc/library/functions.rst I saw that there is a :noindex: directive on that entry. I also noticed that there are :noindex: directives on several other entries in that doc page. I tried removing them all and ran make htmlview, but then I noticed warning messages in the output of make htmlview that said, for example:

WARNING: duplicate object description of bytearray, other instance in library/stdtypes, use :no-index: for one of them

I found this Sphinx documentation that talks about directives that are similar to :noindex:. I don't fully understand it. I tried replacing all the :noindex: directives in functions.rst with :no-index-entry: directives. I noticed two effects from doing that:

1. (Good) It silenced the warnings and the entries appeared in the side nav. (Actually I can't get those warnings to show up anymore no matter what I do, even if I delete the Doc/build/ directory and run make htmlview again.)
2. (Bad) When I use the docs search page to search all the docs for "list", the results are different when :noindex: and :no-index-entry: are used on the list() entry in Doc/library/functions.rst:
   • With :noindex:, the fifth search result for "list" is "list (Python class, in Built-in Types)" and links to Doc/library/stdtypes.rst#list.
   • But with :no-index-entry:, the fifth search result for "list" is "list (Python class, in Built-in Functions)" and links to Doc/library/functions.rst#list. (Also, the entry for list() in functions.rst attempts to link to the entry in stdtypes.rst, but the link instead now links back to the same entry in functions.rst.)

Since the definition in stdtypes.rst is more complete, changing the search result for list() is undesirable.

Does anyone know a way to make these entries show up in the side nav on the functions.rst page without changing other behaviors? Maybe instead of auto-generating the side nav content it could be manually, explicitly defined?

---

📚 Documentation preview 📚: https://cpython-previews--128010.org.readthedocs.build/

[ghost]

All commit authors signed the Contributor License Agreement.

[tomasr8]

cc @AA-Turner as a sphinx expert

[AA-Turner]

This is somewhat moot as we reverted the sidebar object descriptions. But probably worth fixing if we bring them back.

A

[dcki]

Sounds good. Should I close this pull request?

[AA-Turner]

Ok!