Repository navigation
Conversation
Jackenmen
requested review from
AA-Turner,
ZeroIntensity and
willingc
as code owners
October 16, 2026 16:13
Documentation build overview
|
Contributor
Author
|
Since the time I experienced the described story, |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note: this is recreation of #140070 whose review I completely missed until the PR got closed and then, since it was already closed, it waited on my TODO list for a while, sorry for that!
The review comment from the original PR has been addressed by renaming C API docs'
slice-objectsanchor toc-api-slice-objects. This seems consistent with at least some of the other anchor names used in C API docs + that anchor was not used at all anyway.Below is the description copied from #140070 pretty much as is.
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
slicelink, 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
sliceis listed in the Built-in Types document and links to "The standard type hierarchy" part of the Data model docs (the actual "slice object" was not a ref so I updated that in this PR too), 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 howstaticmethoddocumentation in "Built-in Functions" links to "The standard type hierarchy" section.I guess, it's not ideal that the
slicedocumentation is spread across "Built-in Functions" (where thestart,stop, andstepattributes are listed with.. attribute::, though not really documented) and "Data model" (where theslice.indicesmethod 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.