Yes, it’s fine to open a few as drafts. But if you want to do lots, it’s easy to turn on Read the Docs for your fork and do PRs to your fork (or enable extra versions (=branches) in the settings).
1 Like
I closed my PR since I think PR 125757 exceeds my expectations. Thanks @AA-Turner. 
2 Likes
Hmm, I kind of wish the sidebar was resizable now.
1 Like
I also strongly support summary tables at the top—executive summaries with a concise overview of all the things and what they do would help me know where to go quickly.
Summary tables would act as an immediate roadmap and context, showing me where to focus without diving deep into the content right away.
Also, a table of all the things in the main content with a brief description might help me avoid parsing each item and thinking “what does that mean?” — what I might do if only the method name is listed in the sidebar. Example: in the math module example above—fabs description is helpful, I might have naturally know what abs is in the context of math, but fabs took just a bit of thought, slowing me down… a summary would just put the answer there right in front of me.
4 Likes
I pushed 2 PRs, one for each version:
I prefer the single table version. As @surfaceowl wrote, the table(s) add more information than the list in the sidebar, at the price of more space.
4 Likes
Thanks @Nodd for the previews. They are helpful to visualize options. I also prefer the Single table over multiple tables.
I think that I like combining both the table and the sidebar together.
3 Likes
This has been merged, see e.g. os — Miscellaneous operating system interfaces — Python 3.13.0 documentation
If it turns out to be too disruptive we can revert the change.
A
1 Like
Is it possible to allow the sidebar to be a bit wider?
It seems odd to scroll the sidebar horizontally rather than expand it, when there is plenty of room to expand into without significantly changing the look of the page. I recognize that visual design that works for many screen sizes is hard, so no worries if that’s out of scope.
2 Likes
It looks nice, thanks!
I noticed that some entries not listed in the sidebar for the builtins (I might have missed some):
dictfrozensetlistmemoryviewstr
Is it because they are classes and not functions?
Others like bool, float and int are there, but without parentheses.
2 Likes
Could we add an option to collapse the list under a heading?
I.e. a triangle pointing down or right to hide all the function links so that it’s easier to see the page structure in the menu.
Alternatively, a single action «Collapse level 3 headings» or better wording to apply to all the sidebar at once.
2 Likes
Agreed. The lists of functions are very long, and I find seeing the page structure a much more useful feature of the sidebar. Ideally, I’d prefer it if the list of function links were collapsed by default.
1 Like
@merwok and @pf_moore Thanks for sharing your preferences. I have been thinking about the subject of collapsing things on the sidebar. I think there is still work to be done as we iterate on improvements. We are balancing:
- default to open or collapsed
- which level to collapse
- which pages have a long sidebar, how many pages, and whether to refactor those pages
- discoverability of items that are closed
- and likely others…
We will discuss at the community docs meeting as well as continuing discussions here.
3 Likes
This is an example of a page where personally I think it is better to split into multiple pages. This would be straightforward in this case because it already has subheadings
This page (the os module docs) seems to have about 450 separate items documented. Compare that to shutil (our earlier example) which has about 25; there it makes sense to keep them all on one page. str methods (if we split the documentation of this type out to its own page) seem to number around 50, which probably could still be on one page, especially as many have fairly short docs.
It seems clear to me that decisions about splitting out into separate pages should be based both on the number of items documented and on the overall page length. It’s similar to how we organize source code: if I have a class with 450 methods, or a single module that is growing to a huge size, it becomes cognitively difficult to work with. The same applies to docs.
1 Like
As pointed out before, the problem is the backward compatibility of all the links pointing to the existing pages, including intersphinx links. So even if splitting the pages would be a simple modification, the environment makes it far from trivial.
Then maybe there is a need to reevaluate the documentation generation procedure.
I have also wondered whether it would be better for the internal links to link specifically to the version being documented (i.e., not have everything like to docs.python.org/3 but to docs.python.org/3.11 or whatever). Then old links would remain valid. If we are constantly generating documentation that links to /3 and we don’t feel we can change the link scheme in future versions, that would seem to be a burdensome constraint on improving the docs.
Back to the initial subject: I updated the “single table” PR to add the arguments, see for yourself. I choose to not mark default, positional-only nor keyword-only arguments in the table to keep it as light as possible. isclose being over two lines is already bugging me 
1 Like
I’ve just noticed that the contents page itself in “The Standard Python Library” now has all the individual built in functions and constants listed:
This is terrible, IMO, as it makes the contents page much harder to use as a navigation page, which is my main use for it. I now have to scroll down past the builtin functions (that I rarely need) to get to the module listing that I use many times a day.
Is there anywhere that the justification for this change has been recorded, so that I can register my objection, or is this thread the correct place? I would really like this change to be reverted 
3 Likes
Paul, Thanks for bringing this up. Instead of reverting, please give us a few days to edit the settings so the main table of contents isn’t showing the extra level of detail.
1 Like
No rush - my concern was that, given this is on the live site, it was a final decision that would be troublesome to revert or improve. If you’re still experimenting to find the best settings, that’s fine.
1 Like
Thanks Paul!
1 Like