Add examples to docs for str methods

[hauntsaninja]

@adorilson already opened a PR for this over at #105670. If people have higher level feedback on the suggestion, this issue is a good place to do it.

Maybe cc @CAM-Gerlach in case you're interested :-)

Linked PRs

• gh-106318: Add examples to str method entries #105670
• gh-106318: Add examples for the str methods in collapsible sections #111743
• gh-106318: Add string method examples #119445
• gh-106318: Add an example for str.capitalize() #134272
• gh-106318: Add example for str.center() #134518
• gh-106318: Add example for str.count() #134519
• gh-106318: Add example for str.encode() #134520
• gh-106318: Add example for str.endswith() #134523
• gh-106318: Add example for str.expandtabs() #134525
• [3.14] gh-106318: Add example for str.center() (GH-134518) #134571
• [3.13] gh-106318: Add example for str.center() (GH-134518) #134572
• [3.13] gh-106318: Add example for str.count() (GH-134519) #134573
• [3.14] gh-106318: Add example for str.count() (GH-134519) #134574
• gh-106318: Add example for str.find() #134529
• [3.14] gh-106318: Add example for str.encode() (GH-134520) #135457
• [3.13] gh-106318: Add example for str.encode() (GH-134520) #135458
• [3.14] gh-106318: Add example for str.endswith() (GH-134523) #135459
• [3.13] gh-106318: Add example for str.endswith() (GH-134523) #135460
• [3.14] gh-106318: Add example for str.expandtabs() (GH-134525) #135476
• [3.13] gh-106318: Add example for str.expandtabs() (GH-134525) #135477

[terryjreedy]

The main question is whether the examples are worth the space. For some readers, details are definitely useful. I wonder if some of them might better be put inline in the description.

[adorilson]

Hi, folks. Thank you for your review and suggestions. All of them were applied (letting For example at the end of the paragraph). Maybe except in the splitlines method. It is because there is a table between the first paragraph and the example. So, we can:

1. Leave as is
2. Move the example (maybe just the first one) to after the first paragraph

Another idea here?

Another thing is about versionadded:: 3.2. What do you think about removing it.
The reason is that 3.2 is an old version (after end-of-file)? There are some rules about this?

[rhettinger]

The main question is whether the examples are worth the space.

I think the answer is mostly "No". In my courses, I ask people to read the string docs to become familiar with the methods. What I've learned is a) the docs are clear enough without having an example, and b) it already is too long and tedious to read.

IMO, a well-intended effort to add examples would be counter-productive and make the docs less useful. Also, it is already trivially easy to run experiments to verify understanding (the string methods require almost no setup to try out).

FWIW, the argparse docs are a example (no pun intended) of the consequences of going overboard with examples. Instead of one or two informative examples for the whole module, they are were added at a fine-grained level. As a result, we almost never can get anyone to read the docs top to bottom to gain a full understanding of the module.

[AlexWaygood]

Perhaps we could put these examples in expandable sections that are hidden by default, like we recently did for the "relevant PEPs" section of the typing docs: https://docs.python.org/3.12/library/typing.html#relevant-peps.

[adorilson]

Perhaps we could put these examples in expandable sections that are hidden by default, like we recently did for the "relevant PEPs" section of the typing docs: https://docs.python.org/3.12/library/typing.html#relevant-peps.

Do you mean something like this? And @rhettinger, what do you think about it?

[AlexWaygood]

Do you mean something like this?

yes

[adorilson]

Hi, people.

I opened a new PR (#111743 ).
As said there, I would like a "go ahead" to confirm that the work will be valid.