classification
Title: add a "class str" entry to the docs
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.3
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: chris.jerdonek, docs@python, eric.araujo, ezio.melotti, ncoghlan, python-dev, terry.reedy
Priority: normal Keywords: patch

Created on 2012-10-12 09:03 by chris.jerdonek, last changed 2012-11-28 09:50 by chris.jerdonek. This issue is now closed.

Files
File name Uploaded Description Edit
issue-16209-1-default.patch chris.jerdonek, 2012-11-25 06:08 review
issue-16209-2-default.patch chris.jerdonek, 2012-11-25 18:07 review
issue-16209-3-default.patch chris.jerdonek, 2012-11-28 04:53 review
Messages (10)
msg172733 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-12 09:03
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`.
msg172795 - (view) Author: √Čric Araujo (eric.araujo) * (Python committer) Date: 2012-10-13 04:12
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.
msg172797 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-13 05:36
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.
msg176331 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-25 06:08
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.
msg176337 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-11-25 10:47
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.
msg176338 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-11-25 10:51
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).
msg176377 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-25 17:22
> 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.
msg176380 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-25 18:07
Updating patch to fix up affected/related index entries.
msg176509 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-28 04:53
Attaching new patch to address Ezio's suggestions on Rietveld.
msg176525 - (view) Author: Roundup Robot (python-dev) Date: 2012-11-28 09:46
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
History
Date User Action Args
2012-11-28 10:03:18chris.jerdoneklinkissue16205 superseder
2012-11-28 09:50:51chris.jerdoneksetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2012-11-28 09:46:22python-devsetnosy: + python-dev
messages: + msg176525
2012-11-28 04:53:58chris.jerdoneksetfiles: + issue-16209-3-default.patch

messages: + msg176509
2012-11-25 18:07:56chris.jerdoneksetfiles: + issue-16209-2-default.patch

messages: + msg176380
2012-11-25 17:22:02chris.jerdoneksetmessages: + msg176377
2012-11-25 10:51:45ncoghlansetmessages: + msg176338
2012-11-25 10:47:22ncoghlansetmessages: + msg176337
2012-11-25 06:08:32chris.jerdoneksetfiles: + issue-16209-1-default.patch

nosy: + terry.reedy, ncoghlan
messages: + msg176331

keywords: + patch
stage: patch review
2012-10-13 05:36:22chris.jerdoneksetmessages: + msg172797
2012-10-13 04:12:32eric.araujosetnosy: + eric.araujo
messages: + msg172795
2012-10-12 11:44:12ezio.melottilinkissue16205 dependencies
2012-10-12 09:03:17chris.jerdonekcreate