Group the docs of similar methods in stdtypes.rst

[ezio-melotti]

BPO	23560
Nosy	@rhettinger, @ezio-melotti, @berkerpeksag, @vadmium, @csabella
PRs	gh-67748: DOC:Add summary table for str methods in stdtypes.rst #1709
Files	str-groups.patch: Groups str() methods

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2015-03-02.09:28:10.370>
labels = ['easy', 'type-feature', 'docs']
title = 'Group the docs of similar methods in stdtypes.rst'
updated_at = <Date 2019-08-09.02:38:23.499>
user = 'https://github.com/ezio-melotti'

bugs.python.org fields:

activity = <Date 2019-08-09.02:38:23.499>
actor = 'Philip Dye'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2015-03-02.09:28:10.370>
creator = 'ezio.melotti'
dependencies = []
files = ['39506']
hgrepos = []
issue_num = 23560
keywords = ['patch', 'easy']
message_count = 5.0
messages = ['237036', '244101', '294049', '294080', '294117']
nosy_count = 7.0
nosy_names = ['rhettinger', 'ezio.melotti', 'docs@python', 'berker.peksag', 'martin.panter', 'cheryl.sabella', 'Philip Dye']
pr_nums = ['1709']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue23560'
versions = ['Python 2.7', 'Python 3.5', 'Python 3.6']

[ezio-melotti]

The Doc/library/stdtypes.rst page describes in detail the built-in types and their methods. As suggested in bpo-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.

[vadmium]

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.

[csabella]

Hi Martin,

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

Thanks!

[rhettinger]

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.

[csabella]

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!

[OTheDev]

@encukou Can this issue be closed?