Message172797
Let me start over with what I'm suggesting, because the idea wasn't fully developed when I first filed this issue.
I'm thinking that we should create a class entry for str that contains the current string methods nested beneath it -- a bit like issue 12901. :) In conjunction with that, we should move the documentation of the str() function to the constructor for that class entry. All str links throughout the documentation would go to the class entry, and the built-in function str() would be a stub entry that also links to the class entry. That's how we do it for dict, for example:
http://docs.python.org/dev/library/functions.html#func-dict
One reason is practical. By doing the above, clicking "str" anywhere in the docs will take you to the documentation for both the function str() and the string methods. When I was first learning Python, it was very common for me to look up the "String Methods" section. But looking them up never seemed as convenient as it should be because they were in a different location. I always had to remember they were an extra click or two away in a separate "String Methods" section.
In 3.3 we made a bit of progress on this by giving the string type its own section:
http://docs.python.org/dev/library/stdtypes.html#text-sequence-type-str
But we could go further by doing what we do for list, tuple, set, memoryview, range, etc. and put the documentation of the str() function and its methods next to each other in the same location. |
|
Date |
User |
Action |
Args |
2012-10-13 05:36:22 | chris.jerdonek | set | recipients:
+ chris.jerdonek, ezio.melotti, eric.araujo, docs@python |
2012-10-13 05:36:22 | chris.jerdonek | set | messageid: <1350106582.28.0.135756693633.issue16209@psf.upfronthosting.co.za> |
2012-10-13 05:36:22 | chris.jerdonek | link | issue16209 messages |
2012-10-13 05:36:21 | chris.jerdonek | create | |
|