Skip to content

Conversation

Jackenmen
Copy link
Contributor

@Jackenmen Jackenmen commented Oct 14, 2025

Story time!

With the way the documentation is currently organised, I expect to find information about built-in functions/types on the Built-in Functions page.
Sure enough, slice() is on that list, and it starts as follows: "Returns a :term:`slice` object".
Since I needed more information than was already provided, I clicked on the slice link, which directed me to the glossary. Information there, however, still did not include the more detailed information that I was looking for. The glossary entry has a :class:`slice` link, but that just links back to Built-in Functions.

So, that's how this PR came about - I eventually found that slice is listed in the Built-in Types document and links to "The standard type hierarchy" part of the Data model docs, where I found the remaining pieces of information. I think it makes sense to add "See also" links to the function and probably glossary as well. This is similar to how staticmethod documentation in "Built-in Functions" links to "The standard type hierarchy" section.

I guess, it's not ideal that the slice documentation is spread across "Built-in Functions" (where the start, stop, and step attributes are listed with .. attribute::, though not really documented) and "Data model" (where the slice.indices method is documented + aforementioned attributes are better documented and :ref:ed) but I wanted to at least make it easy to find the information through links.

I did not make an issue since this seems like a trivial docs enhancement, but please let me know if I should do so.


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

@bedevere-app bedevere-app bot added docs Documentation in the Doc dir skip news labels Oct 14, 2025
@github-project-automation github-project-automation bot moved this to Todo in Docs PRs Oct 14, 2025
@Jackenmen Jackenmen marked this pull request as ready for review October 14, 2025 00:07
when several are given, such as in ``variable_name[1:3:5]``. The bracket
(subscript) notation uses :class:`slice` objects internally.

See also :ref:`slice-objects`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When I click the rendered link in the preview, it sends me to the C-API docs and not the data model docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

2 participants