homepage

This issue is to add a str class entry to the built-in types page like we have for dict, set, memoryview, etc:
http://docs.python.org/dev/library/stdtypes.html
This will let us reference ``str`` the class separately from ``str()`` the built-in function. It will also let us remove the "str." prefix from all of the string method descriptions. Thirdly, it will make the str documentation match what is being done for the types previous to it in the documentation, including the range, tuple, and list classes. Lastly, it will make referencing string-related sections in Sphinx a bit more intuitive. Currently, :class:`str` points to the built-in function :func:`str`.

This sort of request came up before, the last time only a few months ago if memory serves. The shot answer is that str is a built-in function as well as a class, and trying to split hairs over that does not really add value to the docs. I can dig up the issue(s) if you don't find them.

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.

Attaching patch.
Adding Nick to the nosy list because he did the work of originally breaking out the "Text Sequence Type" section for issue #4966, as well as Terry who created that issue. I view the current issue and patch as a progression of some of the issues discussed in that issue.

Right, aside from my recent revamp, much of the existing layout of the types section has been inherited from the pre-new style classes days when you *couldn't* inherit from types, and strings were the only one with a non-trivial number of methods.
Rearranging as Chris suggests makes sense to me - my work was certainly only intended to be the *start* of improvements to the builtin type docs.
The main thing to watch out for is ensuring we don't break any incoming deep links while rearranging things (perhaps by adding the appropriate explicit anchor targets). It's OK if some cases end up just linking to the page (e.g. that's what now happens to reference to the old monolithic sequence types section, as there's no obviously better destination), but in this case the old deep links should go to the new class docs.

The simpler approach Chris has taken here (i.e. just leaving the string methods separate from the class definition) also works.
Patch looks good to me - I'm definitely in favour of moving towards a more consistent approach of having the builtin function definitions reference to full class definitions (as shown by the changes I made to the docs for the other sequence types).

> The simpler approach Chris has taken here (i.e. just leaving the string methods separate from the class definition) also works.
Yes, though I mentioned nesting the string methods beneath the class entry in the original post for this issue, I figured we could start smaller and do this in more manageable steps. We can do the bigger change (in the sense of being a bigger diff) of indenting as part of a second issue/patch.

Updating patch to fix up affected/related index entries.

Attaching new patch to address Ezio's suggestions on Rietveld.

New changeset 0097379df2e1 by Chris Jerdonek in branch '3.3':
Add a str class entry to the "Text Sequence Type" section (issue #16209).
http://hg.python.org/cpython/rev/0097379df2e1
New changeset 81ac75c64780 by Chris Jerdonek in branch 'default':
Merge from 3.3: Add a str class entry to the string section (issue #16209).
http://hg.python.org/cpython/rev/81ac75c64780