Repository navigation
Add examples to docs for str methods #106318
Description
@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
strmethods 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
Activity
terryjreedy commentedon Jul 1, 2023
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 commentedon Jul 3, 2023
Hi, folks. Thank you for your review and suggestions. All of them were applied (letting
For exampleat the end of the paragraph). Maybe except in thesplitlinesmethod. It is because there is a table between the first paragraph and the example. So, we can: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 commentedon Jul 9, 2023
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 commentedon Jul 9, 2023
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 commentedon Sep 17, 2023
Do you mean something like this? And @rhettinger, what do you think about it?
AlexWaygood commentedon Sep 17, 2023
yes
AA-Turner commentedon Sep 19, 2023
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
adorilson commentedon Nov 4, 2023
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.
ezio-melotti commentedon Jan 23, 2024
We recently had a few discussions related to this, including in the last docs-community meeting or on Discord.
The relevant bits are:
.. 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
strmethods, it might be better to just add the examples at the bottom of the page (like I did for thestr.formatdocs) 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).Merge pull request #1 from blaisep/pr-105670
Merge pull request #2 from blaisep/main
Add an example for `str.casefold`
Add example for `str.center()`
Add example for `str.count()`
268 remaining items
pythongh-106318: Add examples for str.isspace() docs
[3.14] gh-106318: Fix incorrectly rendered code block in `str.isalnum…
[3.13] gh-106318: Fix incorrectly rendered code block in `str.isalnum…
gh-106318: Add examples for str.isspace() docs (#145399)
pythongh-106318: Add examples for str.isspace() docs (pythonGH-145399)
pythongh-106318: Add examples for str.isspace() docs (pythonGH-145399)
[3.14] gh-106318: Add examples for str.isspace() docs (GH-145399) (#1…
[3.13] gh-106318: Add examples for str.isspace() docs (GH-145399) (#1…
gh-106318: Add example for str.swapcase() method (#144575)
pythongh-106318: Add example for str.swapcase() method (pythonGH-144575)
pythongh-106318: Add example for str.swapcase() method (pythonGH-144575)
[3.14] gh-106318: Add example for str.swapcase() method (GH-144575) (#…
[3.13] gh-106318: Add example for str.swapcase() method (GH-144575) (#…
pythongh-106318: Add examples for `str.startswith()` method (python#1…
pythongh-106318: Add example for str.isalnum() (python#137550)