Generate separate pages for every individual free function and class

[adamncasey]

The problem

One issue I come across quite frequently when searching for python documentation is that I can find the page the function docs exist on quite quickly. But getting to the actual function on that page isn't obvious or (often) easy.

For example, searching for python os.pipe gives me a first result of https://docs.python.org/3/library/os.html but it drops me at the top of a fairly long page with no easy way to jump to what I'm actually looking for.

I've learned I can typically ctrl+f for the function name I'm looking for. In the example above the actual function would be the third result, although I could have clicked the second result to jump there.

It's certainly not unusable, but it does make the official python docs one of the hardest results to navigate - which is a shame because the quality (and authenticity) of the information here is excellent.

The above example is not so bad, but the length of pages such as https://docs.python.org/3/library/stdtypes.html is surprisingly daunting when you want to check what the official docs say about a pretty 'core' behaviour such as dict.get()

I think pages such as https://docs.python.org/3/library/functions.html which add a table of contents to the top are a slight improvement, but they don't really solve the problem that if I search for python open function I would like to immediately see information relevant for my search - abs() / all() don't fit that bill.

Solutions in other doc sites/languages

Looking at other programming languages, this problem is solved by having a hierarchy of pages such as:

• top level: module documentation
  • C++ <unordered_map> header file
  • Rust std::collections
  • C# System.Collections.Generic
• next level: free function / class documentation
  • C++ unordered_map class
  • Rust HashMap class
  • C# Dictionary
• next level: class member documentation
  • C++ unordered_map::at
  • Rust doesn't have separate pages at this level, but the class/module documentation is much more targetted. Finding get from the class docs is significantly easier because these methods are listed above the fold on the left hand table of contents.
  • C# Dictionary.TryGetValue

Suggestion

I think adding more structure into the docs.python.org pages, even if it means some information gets duplicated, would be a bit improvement for search -> find workflows for function documentation.

I think there should be a page specifically for the dict class, if not to a page specifically for every method. This should eventually improve the search -> result experience but it will also makes it much easier for the user to discover other relevant functions/info - such as dict[key], or dict.update

It may also give the official python docs a boost in search engine ratings for searches like python dict update - at the moment (at least in my google results) I need to hop over a lot of advert filled or specifically python2.7 only tutorial/reference pages - and I don't blame google

Thanks for reading & I hope this is the right place to open an issue. Let me know if I should be directed elsewhere.

[JulienPalard]

I agree! But I don't think it can be automated at build time, it's a redactional work, so can you please open it in https://github.com/python/cpython/issues/?

[hugovk]

Let's close this issue, it was discussed in python/cpython#100921.