I think that my PR is ready to be merged. If not, please tell me what to improve.
My PR was merged, thanks! Itās my first official contribution to Python 
I followed up with another summary table, this time for pathlib: PR, Preview. The number of attributes and methods is quite big: 6 classes, 11 attributes, 59 methods. Despite the good documentation, it can be hard to remember them all. I hope that this table can be of help.
6 Likes
Whatās the progress on this? The library docs still have expanded āBuilt in Functionsā and āBuilt in Constantsā sections on the main page, and the decrease in usability is significant (for me, at least) compared to the 3.11 and earlier docs.
3 Likes
Sorry, slipped my mind. Iāll have another look now.
A
2 Likes
Iāve made a terser summary table for pathlib in this PR A more compact pathlib summary by nedbat Ā· Pull Request #127911 Ā· python/cpython Ā· GitHub
- Removed class names and parameters from the summary
- Used parentheses uniformly to indicate methods
- Shortened some of the summary descriptions (more could be done here)
- Moved āexceptionsā to the end
My goal was to let the most pertinent information (the method name) stand out, and to keep the table rows short for smaller screens.
Doc build preview: pathlib ā Object-oriented filesystem paths ā Python 3.14.0a1 documentation
1 Like
Another gentle ping on this. I appreciate that itās one job among many, but personally if itās likely to take some time to improve the situation, Iād be in favour of simply reverting the previous change in the meantime - the current behaviour is a significant regression.
3 Likes
This is much better on mobile. Left is the earlier python/cpython#126342 and right is the new python/cpython#127911:
6 Likes
I quite like this proposal @nedbat overall; this removes a lot of redundant information, which makes the whole table easier to read and cleaner (across viewport sizes, including mobile).
2 Likes
What if this top summary has only the top-level element? The classesā attributes and methods would be in a class-level summary.
The summary would be cleaner, and the attributes/methods would be contextualized more.
TBH, Iām not sure the best approach. The math page has a summary table with parameters included. But those function names are short, and the parameter names tend to be short, so it doesnāt cause a problem there.
Indeed, math mostly has short function names with just one or two single-character parameters, and they donāt make the table too wide.
I think itās okay to pick whichever style makes sense for a given table, and be consistent within that table.
8 Likes
Is it worth me raising an issue for this? Itās been a couple of months now and for me itās a serious usability problem. If having an issue will make it less likely to fall off peopleās radar, Iām happy to raise one, but I donāt want to create more admin if it wonāt help.
3 Likes
Letās give a few more days until the new year in case @AA-Turner is available, but I think by now we could just revert it (python/cpython#125757 is the PR in question), and it can always be fixed and re-applied later.
3 Likes
Iāve opened python/cpython#128406 to revert.
1 Like
Now reverted (in #128406). To solve this elegantly we might need to add a new feature to Sphinx ā we want to exclude object descriptions from the āglobalā table of contents (generated by the .. toctree:: directive), but still to include them on each individual page.
Sorry for the disruption here!
A
4 Likes
Confirmed, the TOC page is now back to its old form. Thanks for this!
I created a similar post, not knowing about this one. I do think my thoughts are slightly different.
I do not like the summary in the sidebar. They do make the sidebar look too messy and take up too much horizontal space. It is easy to click the link to the section.
(Regarding horizontal space, I really hate it when sidebars are wide and do not have any way to change width or hide when the browser window is narrowed. It can make a page almost unusable when the browser is half the width of a typical screen.)
I still think the idea of adding collapsible items that expand to show a list are the best way to provide a more full featured TOC and still allow keeping it compact for normal/default viewing.
My primary wants are a list of classes, methods for each class and functions for each module. I am constantly using āfindā in the browser to get to the function I want. An even bigger issue is that I cannot search unless I know what function I am looking for. As far as I know, there isnāt even a list of functions or methods in the body of the doc, which leaves the user to read through the entire documentation to see what is there.
My topic is at Improve documentation page navigation, specificly by adding a function list and I am going to mark it as closed.
2 Likes
Thanks for bringing this subject back! I confirm that this is my goal as well. I tried to work towards this, but I found that it was complicated to converge towards a solution fitting every page, because each module documentation seems maintained by different people with different views on what is best. My idea was to incrementally add tables to the documentation, but lack of consensus and lack of time on my side made me stop for now.
I think a larger hurdle is that different pages need different approaches. Pathlib and builtins have different needs, so itās very hard to find a one-size-fits-all solution, or even a crisply defined rubric about how to approach each page.
See A more compact pathlib summary by nedbat Ā· Pull Request #127911 Ā· python/cpython Ā· GitHub for a discussion about Pathlib.
2 Likes