The Python documentation is really great, but the long pages can be intimidating and hard to navigate. As an example, what are the methods of the str type ? You have to scroll through the 47 methods in the middle of the larger builtins page to check what is possible to do with a str object. One solution to this is to add summaries at the top, which enables to have a quick overview of the functions of a module or the methods of a class, as it was done for the statistics module.
Pros:
Newcomers can quickly grasp what a module or a class is for
Advanced users can quickly remember the list and check the writing (is it isfile or is_file?)
Documentation would be more similar to other tools or languages, as was discussed in another topic
Cons:
It would make the documentation pages even longer
It would need to keep in sync multiple parts of the documentation when adding new members
If this is seen as a benefit, Iâm volunteering to add these tables to some modules. Iâm fine with an answer like âpropose a PR and see how it goesâ, but if there are some consensus first if would make my work easier
I think itâs a good idea, although in many cases I think itâd be even better to actually split the documentation for many types out to separate pages. Maybe this doesnât need to be done for every type, but for types like str that are ubiquitous and have many useful methods, I think it would be much handier than having them buried in the midst of a long page about all builtins.
One of the technical problems we have with that kind of change is that we donât have a nice way to keep deep links to the old structure working.
The summary tables at least mitigate the problem without breaking anything (theyâre just a hassle to write in the first place, hence their ad hoc inclusion).
If you mean links like https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str, I donât think they need to keep fully âworkingâ. There can still be a brief paragraph at that point in the docs that says âTextual data in Python is handled with str objects, or strings. See full documentation on the str type here (link to new page).â
Yeah, well, I guess we have to choose between breaking those links and having a giant file where itâs difficult for humans to find the information they want. I know which one Iâd prefer.
I donât think we do, since it would be possible to use a different file name for a restructured version and make the old page an orphan with explicitly defined anchors containing semantic links to the updated locations.
I agree that splitting some pages would be an improvement, but even if it was done, having summary tables would be useful. str will still have 47 members! Both improvement are orthogonal for the most part, so letâs start with the easier part.
The first version adds another level of sections, which mirrors the sections of the rest of the page. Itâs less compact, looks weird when there are a few functions in a section (see Angular conversion for example, and itâs a bit more complicated to integrate into the page flow. The advantage is that itâs not a single huge table.
The second version is easier to insert and looks cleaner, but itâs a bit too big.
A third possible option is to insert the multiple table in each section. It would look good but it would lose the âwhat is in this moduleâ effect.
I did not push these changes yet, I want to check the workflow first. Itâs my first time proposing a modification to CPython
This seems okay for this case. This is different from str because the entire page is about top-level functions in one module. The problem with str (and other builtins) is that all methods for all builtin types are dumped into one big page.
I donât see the advantage of this over having the contents in the sidebar. The advantage of the sidebar is that it is separately scrollable so you can jump to any method no matter where you are on the page. With a table at the top you always have to scroll back to the top to find what you want.
This seems like overkill to me for a case like this where most of the functions have relatively modest-sized documentation. A separate page for one method could be useful for cases like Popen that have long individual docs, but I think in most cases itâs useful to have related methods on one page.
There is another option you didnât mention, which is to split each section onto a separate page. I probably wouldnât do that here as the last section has only one function, but in some other cases it could be appropriate.
For me the relevant considerations are conceptual units and overall size of the page. I think there is a âsweet spotâ of medium-sized pages where you can conveniently jump from one to another and/or use Ctrl-F to search around, but not lose track of where you are. A separate page for each method/function is usually unwarranted. The most egregious cases are ones like the mentioned builtin types one where a huge number of quite distinct types and their methods are all on one page. But usually having a single type and its methods documented on a single page seems good to me.
Some of the side menus are far too long and crowded. In January, we added a setting to prevent them getting even longer and more crowded: python/cpython#114318.
I think tables at the top can be useful, especially if in many cases you want to find a thing, and when done, can close the page. No need to navigate back to the top again. See the built-in functions for one example. It would be good if Sphinx could generate them rather than manually building them.
I think itâs worth looking into separate pages per method, or at least breaking some of the huge pages into more manageable chunks. Some of our pages are huge, which are hard to navigate and bad for SEO.
Another idea is to change the theme. At the core sprint, I made a quick demo using the PyData Sphinx Theme, as used by projects such NumPy. This is a quick demo, the header and footer and other custom stuff would need adjusting, but a big benefit is thereâs a less cluttered left-hand menu, and it also adds a right-hand menu. Weâd also benefit from the huge amount of work being put into the theme, including lots of accessibility work.
I wonder if it is possible to have both modes available using the same source material and some toggle in the URL or somewhere else. I havenât thought deeply about the layout but it seems like it should be possible[1].
Thereâs something poetic about re-creating the âall one pageâ vs âHTML treeâ options from 30 years ago.
An alternative to this which âresolvesâ the long attribute names problem is PR 125757:
The proposed solution is stopping attribute names from breaking over lines and adding horizontal scroll.
The contents in the sidebar do become much longer, but the pages themselves are quite long - and this does help faster access to each name. Personally I think the trade-off is worth it, though others may disagree.
