Description

hauntsaninja

opened on Jul 1, 2023

Issue body actions

@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
• gh-106318: Add example for str.format() #137018
• gh-106318: Add example for str.index()  #137023
• gh-106318: Add example for str.isalnum() #137550
• gh-106318: Add example for str.isalpha() #137557
• gh-106318: Add example for str.isascii() #137558
• gh-106318: Add example for str.isdecimal() #137559
• [3.14] gh-106318: Add example for str.find() (GH-134529) #138174
• [3.13] gh-106318: Add example for str.find() (GH-134529) #138175
• gh-106318: Add example for str.isprintable()  #140043
• gh-106318: Add examples for str.istitle()  #140046
• [3.14] gh-106318: Add examples for str.istitle() (GH-140046) #140113
• [3.13] gh-106318: Add examples for str.istitle() (GH-140046) #140114
• gh-106318: Add examples for join() #140314
• gh-106318: Add examples for str.join() #140315
• [3.14] gh-106318: Add example for str.isdecimal() (GH-137559) #141893
• [3.13] gh-106318: Add example for str.isdecimal() (GH-137559) #141894
• [3.14] gh-106318: Add example for str.isascii() (GH-137558) #141898
• [3.13] gh-106318: Add example for str.isascii() (GH-137558) #141899
• [3.14] gh-106318: Add example for str.isalpha() (GH-137557) #141901
• [3.13] gh-106318: Add example for str.isalpha() (GH-137557) #141902
• [3.13] gh-106318: Add example for str.format() (GH-137018) #141903
• [3.14] gh-106318: Add example for str.format() (GH-137018) #141904
• [3.13] gh-106318: Add examples for str.join() (GH-140315) #141905
• [3.14] gh-106318: Add examples for str.join() (GH-140315) #141906
• gh-106318: Add examples for str.casefold() and str.lower() methods #142154
• gh-106318: Add examples for str.isnumeric() #142680
• [3.13] gh-106318: Add examples for str.isnumeric() (GH-142680) #142716
• [3.14] gh-106318: Add examples for str.isnumeric() (GH-142680) #142715
• gh-106318: Add examples for str.ljust() method  #142719
• [3.14] gh-106318: Add examples for str.ljust() method (GH-142719) #142802
• [3.13] gh-106318: Add examples for str.ljust() method (GH-142719) #142803
• gh-106318: Add example for str.maketrans() #142822
• gh-106318: Add examples for str.partition() method #142823
• [3.14] gh-106318: Add examples for str.isprintable() (GH-140043) #143483
• [3.13] gh-106318: Add examples for str.isprintable() (GH-140043) #143484
• [3.13] gh-106318: Add example for str.index() (GH-137023) #143501
• [3.14] gh-106318: Add example for str.index() (GH-137023) #143502
• [3.14] gh-106318: Add examples for str.casefold() and str.lower() methods (GH-142154) #143524
• [3.13] gh-106318: Add examples for str.casefold() and str.lower() methods (GH-142154) #143525
• gh-106318: Add doctest role and 'See also' for str.removeprefix() #143579
• gh-106318: Improve str.removeprefix() and str.removesuffix() docs #143580
• gh-106318: Add examples for str.replace() method #143581
• gh-106318: Add examples for str.rfind() method #143582
• [3.14] gh-106318: Improve str.removeprefix() and str.removesuffix() docs (GH-143580) #143614
• [3.13] gh-106318: Improve str.removeprefix() and str.removesuffix() docs (GH-143580) #143615
• [3.14] gh-106318: Add examples for str.rfind() method (GH-143582) #143616
• [3.13] gh-106318: Add examples for str.rfind() method (GH-143582) #143617
• [3.13] gh-106318: Add examples for str.replace() method (GH-143581) #143788
• [3.14] gh-106318: Add examples for str.replace() method (GH-143581) #143789
• gh-106318: Add example for str.rindex() method #143887
• gh-106318: Add examples for str.rjust() method #143890
• gh-106318: Add examples for str.rpartition() method #143891
• gh-106318: Improve str.rstrip() method doc #143893
• [3.14] gh-106318: Add examples for str.rpartition() method (GH-143891) #144040
• [3.13] gh-106318: Add examples for str.rpartition() method (GH-143891) #144041
• gh-106318: Add doctest role and a 'See also' item for str.split() #144367
• gh-106318: Add doctest role for str.splitlines() examples #144368
• gh-106318: Add examples for str.startswith() method #144369
• gh-106318: Add a successful example for str.index() method #144408
• [3.14] gh-106318: Add examples for str.rindex() method (GH-143887) #144421
• [3.13] gh-106318: Add examples for str.rindex() method (GH-143887) #144422
• [3.13] gh-106318: Add examples for str.startswith() method (GH-144369) #144480
• [3.14] gh-106318: Add examples for str.startswith() method (GH-144369) #144481
• gh-106318: Add example for str.swapcase() method #144575
• gh-106318: Add link to str.capitalize on the str.title() docs #144578
• [3.14] gh-106318: Add example for str.isalnum() (GH-137550) #144609
• [3.13] gh-106318: Add example for str.isalnum() (GH-137550) #144610
• [3.14] gh-106318: Add examples for str.partition() method (GH-142823) #144611
• [3.13] gh-106318: Add examples for str.partition() method (GH-142823) #144612
• gh-106318: Add examples for str.upper() method and improve related #144638
• [3.13] gh-106318: Improve str.rstrip() method doc (GH-143893) #144698
• [3.14] gh-106318: Improve str.rstrip() method doc (GH-143893) #144699
• gh-106318: Fix incorrectly rendered code block in str.isalnum() docs #144718
• gh-106318: Add examples for str.isdigit() method docs  #144721
• [3.13] gh-106318: Fix incorrectly rendered code block in str.isalnum() docs (GH-144718) #144729
• [3.14] gh-106318: Fix incorrectly rendered code block in str.isalnum() docs (GH-144718) #144730
• gh-106318: Add examples for str.islower() docs #144847
• gh-106318: Improve str.lower() docs #144848
• [3.13] gh-106318: Add examples for str.rjust() method (GH-143890) #145256
• [3.14] gh-106318: Add examples for str.rjust() method (GH-143890) #145257
• gh-106318: Add examples for str.isspace() docs #145399
• [3.14] gh-106318: Add examples for str.isspace() docs (GH-145399) #145752
• [3.13] gh-106318: Add examples for str.isspace() docs (GH-145399) #145753
• [3.14] gh-106318: Add example for str.swapcase() method (GH-144575) #148296
• [3.13] gh-106318: Add example for str.swapcase() method (GH-144575) #148297
• [3.15] gh-106318: Add doctest role and a 'See also' to the str.split() docs (GH-144367) #150908
• [3.14] gh-106318: Add doctest role and a 'See also' to the str.split() docs (GH-144367) #150909
• [3.13] gh-106318: Add doctest role and a 'See also' to the str.split() docs (GH-144367) #150910
• [3.15] gh-106318: Add examples to the str.isdigit() method docs (GH-144721) #151082
• [3.14] gh-106318: Add examples to the str.isdigit() method docs (GH-144721) #151083
• [3.13] gh-106318: Add examples to the str.isdigit() method docs (GH-144721) #151084
• [3.14] gh-106318: Add an example for str.capitalize() (GH-134272) #161324
• [3.15] gh-106318: Add an example for str.capitalize() (GH-134272) #161325
• [3.15] gh-106318: Add link to str.capitalize on the str.title() docs (GH-144578) #161328
• [3.14] gh-106318: Add link to str.capitalize on the str.title() docs (GH-144578) #161329

Activity

1. hauntsaninja

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Jul 1, 2023
2. terryjreedy commented on Jul 1, 2023

   

   terryjreedy

   on Jul 1, 2023

   Member

   More actions

   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.

   Reacted by Shantanu
3. adorilson commented on Jul 3, 2023

   

   adorilson

   on Jul 3, 2023

   Contributor

   More actions

   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?
4. rhettinger commented on Jul 9, 2023

   

   rhettinger

   on Jul 9, 2023

   Contributor

   More actions

   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.

   Reacted by Sergey B Kirpichev
5. AlexWaygood commented on Jul 9, 2023

   

   AlexWaygood

   on Jul 9, 2023

   Member

   More actions

   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.
6. adorilson commented on Sep 17, 2023

   

   adorilson

   on Sep 17, 2023

   Contributor

   More actions

   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?

   
7. AlexWaygood commented on Sep 17, 2023

   

   AlexWaygood

   on Sep 17, 2023

   Member

   More actions

   Do you mean something like this?

   yes

   Reacted by AnubhavB

   Reacted by Adorilson Bezerra
8. AA-Turner commented on Sep 19, 2023

   

   AA-Turner

   on Sep 19, 2023

   Member

   More actions

   The only problem is that man pages, LaTeX, epub, etc (to my knowledge) don't have the concept of expandable sections. See sphinx-doc/sphinx#10532 (comment) for some context.

   On the other hand, this would be useful even if we make the collapsible content HTML only.

   A
9. adorilson commented on Nov 4, 2023

   

   adorilson

   on Nov 4, 2023

   Contributor

   More actions

   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.
10. ezio-melotti commented on Jan 23, 2024

    

    ezio-melotti

    on Jan 23, 2024

    Member

    More actions

    We recently had a few discussions related to this, including in the last docs-community meeting or on Discord.
    The relevant bits are:

    • Adding more examples is generally a good idea. Depending on the context, it can be done inline, at the bottom of the page in an "Examples" section, or as a separate page.
    • There's been some discussion about using collapsible sections (see the issue linked above by @AA-Turner). Using .. raw:: is probably not the right way to go, since there are already extensions that provide the feature. However these are not compatible with all builders, so we can't just use them easily without a fallback for the other builders.

    Until a better solution for collapsible sections is found, and if adding more example inline it's not desirable for the str methods, it might be better to just add the examples at the bottom of the page (like I did for the str.format docs) or possibly in a separate page (this needs a broader discussion though, especially if a similar approach gets adopted for builtin functions and possibly other pages).
11. blaisep

    added 2 commits that reference this issue on May 24, 2024

    Merge pull request #1 from blaisep/pr-105670

    098d9f3

    Merge pull request #2 from blaisep/main

    7e7787e
12. blaisep

    added 3 commits that reference this issue on May 22, 2025

    Add an example for `str.casefold`

    This issue will close once commit 7d3acc4 is merged into the 'main' branch.

    7d3acc4

    Add example for `str.center()`

    This issue will close once commit 8f967fa is merged into the 'main' branch.

    8f967fa

    Add example for `str.count()`

    This issue will close once commit 8132ff5 is merged into the 'main' branch.

    8132ff5
13. 268 remaining items

    Load more actions
14. adorilson

    added a commit that references this issue on Mar 1, 2026

    pythongh-106318: Add examples for str.isspace() docs

    9d9aa84
15. encukou

    added 2 commits that reference this issue on Mar 3, 2026

    [3.14] gh-106318: Fix incorrectly rendered code block in `str.isalnum…

    d8f0ffe

    [3.13] gh-106318: Fix incorrectly rendered code block in `str.isalnum…

    5c77c7d
16. hugovk

    added a commit that references this issue on Mar 10, 2026

    gh-106318: Add examples for str.isspace() docs (#145399)

    9585f50
17. miss-islington

    added 2 commits that reference this issue on Mar 10, 2026

    pythongh-106318: Add examples for str.isspace() docs (pythonGH-145399)

    ea01378

    pythongh-106318: Add examples for str.isspace() docs (pythonGH-145399)

    aff027f
18. hugovk

    added 2 commits that reference this issue on Mar 10, 2026

    [3.14] gh-106318: Add examples for str.isspace() docs (GH-145399) (#1…

    387abcc

    [3.13] gh-106318: Add examples for str.isspace() docs (GH-145399) (#1…

    973323e
19. hugovk

    added a commit that references this issue on Apr 9, 2026

    gh-106318: Add example for str.swapcase() method (#144575)

    d11e9ff
20. miss-islington

    added 2 commits that reference this issue on Apr 9, 2026

    pythongh-106318: Add example for str.swapcase() method (pythonGH-144575)

    eaed43c

    pythongh-106318: Add example for str.swapcase() method (pythonGH-144575)

    e9e8ada
21. hugovk

    added 2 commits that reference this issue on Apr 9, 2026

    [3.14] gh-106318: Add example for str.swapcase() method (GH-144575) (#…

    571c337

    [3.13] gh-106318: Add example for str.swapcase() method (GH-144575) (#…

    8337805
22. ljfp

    added 2 commits that reference this issue on Apr 25, 2026

    pythongh-106318: Add examples for `str.startswith()` method (python#1…

    56a079d

    pythongh-106318: Add example for str.isalnum() (python#137550)

    4d3cef7

Issue actions