classification
Title: Group the docs of similar methods in stdtypes.rst
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.6, Python 3.5, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: berker.peksag, csabella, docs@python, ezio.melotti, martin.panter, rhettinger
Priority: normal Keywords: easy, patch

Created on 2015-03-02 09:28 by ezio.melotti, last changed 2017-05-22 00:58 by csabella.

Files
File name Uploaded Description Edit
str-groups.patch martin.panter, 2015-05-26 13:10 Groups str() methods review
Pull Requests
URL Status Linked Edit
PR 1709 open csabella, 2017-05-22 00:54
Messages (5)
msg237036 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2015-03-02 09:28
The Doc/library/stdtypes.rst page describes in detail the built-in types and their methods.  As suggested in #21777 (see the comments on Rietveld), it might be a good idea to group the documentation of some similar methods, such as {r|l|}just, {r|l|}strip, {r|}partition, {r|}index, and {r|}find.

This will remove some duplication, make the page shorter and easier to navigate, and make the methods easier to discover.  Adding tables containing the methods for each types has also been proposed.
msg244101 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-05-26 13:10
Here is a patch that groups similar methods of the str() class together at various levels.

I added an alphabetical index of the methods, currently as a big paragraph of hyperlinks in the existing String Methods section. Then I added the following seven new sections. Ideally they would be ordered from important to obscure.

* String Formatting
* Searching and Replacing
* Splitting and Joining
* String Classification
* Case Manipulation
* Padding and Stripping
* Translation and Encoding

Within each section, most methods remain separate with no change to their descriptions. Some are grouped under a single description, where a there is an obvious pattern. I have tried put closely related methods nearby, while putting important and simple methods higher up, and moving their obscure and complex counterparts lower down.

Depending on outcome of these changes to the string methods, I may also be interested in doing a similar job to the bytes() and bytearray() methods.
msg294049 - (view) Author: Cheryl Sabella (csabella) * Date: 2017-05-20 20:17
Hi Martin,

Do you think it would be good to move forward with this as a PR?


Thanks!
msg294080 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-05-21 06:53
I don't think this should be done.  Instead, add a table at the top listing the functions in groups, possibly linking to the alphabetical details docs below.

When looking a what a string method does, alphabetical makes the search easier than having to guess which group something is in before you can find it.
msg294117 - (view) Author: Cheryl Sabella (csabella) * Date: 2017-05-22 00:58
I hope this is OK, but I created a version of the patch with a table as Raymond suggested.  I didn't know how to make a patch, so I did it in a PR.  I wanted to have a comparison available to see the differences between the two versions.  I used the original categories as defined by Martin.

I could also add a bytearray column if the table looks reasonable.

Thanks!
History
Date User Action Args
2017-05-22 00:58:24csabellasetmessages: + msg294117
2017-05-22 00:54:43csabellasetpull_requests: + pull_request1800
2017-05-21 06:53:12rhettingersetnosy: + rhettinger
messages: + msg294080
2017-05-20 20:17:09csabellasetnosy: + csabella
messages: + msg294049
2016-01-02 08:14:28ezio.melottisetversions: - Python 3.4
2015-05-27 00:35:57berker.peksagsetnosy: + berker.peksag
2015-05-26 13:10:17martin.pantersetfiles: + str-groups.patch
versions: + Python 3.6
messages: + msg244101

keywords: + patch
stage: needs patch -> patch review
2015-03-03 04:31:34martin.pantersetnosy: + martin.panter
2015-03-02 09:28:10ezio.melotticreate