Issues from docs@python.org

[encukou]

Users who don't have a github login are instructed to report issues to docs@python.org.
I meant to do some triaging before converting the mails to GH issues, but always had something more important to do. So I'm posting a rough list to get more eyes on these. Each has a link to the list post.

(These weren't triaged; they're not necessarily good ideas.)

Tasks

Beta Give feedback

1. typo in socket docs -- Hank Knox
2. asyncio shield typo -- Dyussenov Nuraly - (Fix a code snippet typo in asyncio docs #108427)
3. array -- data type range printed wrong -- Shivansh Verma (gh-110383: Added explanation in Doc about array data types range. Based on GNU docs #113708)
4. EPUB error -- e.g. Glenn Street, Ranjith B, sobi
5. Howto/regex omits the simplest {n} case -- Derek Mead -- (gh-110383: Added explanation about simplest regex use case for quantifiers. #111110)
6. Problem in help for str().rsplit() -- Alan Brogan - (gh-110383: Improve accuracy of str.split() and str.rsplit() docstrings #113355)
7. replacement for deprecation -- SUN Guonian (gh-110383: Remove references to removed popen[234] #112783)
8. Potential typo in Profiler docs? -- 2dfkit
9. timeit -- Arthur Goldberg -- (gh-110383 TimeIt Docs Spelling Fix #110407)
10. list of errata: 1 -- Stephan Stiller
11. list of errata: 2 -- Stephan Stiller -- (gh-110383: Update dict get, fromkeys, and setdefault signatures in docs #119330)
12. list of errata: 3 -- Stephan Stiller -- (gh-110383: Add documentation entry for sorted(d) #112777)
13. list of errata: 4 -- Stephan Stiller - WONTFIX
14. list of errata: 5 -- Stephan Stiller - WONTFIX
15. list of errata: 6 -- Stephan Stiller -- (gh-110383: Improve 'old string formatting' text in tutorial #120219)
16. list of errata: 7 -- Stephan Stiller
17. list of errata: 8 -- Stephan Stiller -- (gh-110383: Explained which error message is generated when there is an unhandled exception #111574)
18. list of errata: 9 -- Stephan Stiller
19. profiler docs inaccuracy -- 2dfkit -- (gh-110383: Fix documentation profile cumtime fix #112221)
20. Tutorial: command for python -c should be consistent with main command #112146
    docs +1
21. Getting tkinter -- Steve Philcox: This complaint is about how to install dependencies when building CPython; this is already covered by the devguide.
22. PDF readability: the colour palette results in too low contrast for highlighted code #120302
    docs type-bug +2
23. Problems in Python tutorial -- Todd Hoatson
24. link from UserList docs to the collections classes list of methods -- Seebs - WONTFIX
25. confusing formatting of “fields” -- Роман Филимонов: this is a common way of marking up the plural variant of something that's marked up using a monospaced font; not a bug
26. socket.makefile -- Michael Gold
27. pow - “integral” is confusing to non-natives -- marc rovira -- (gh-110383: Clarify "non-integral" wording in pow() docs #119688)

Feel free to tick off ones that aren't appropriate, and convert larger ones to their own issues.

Linked PRs

• gh-110383 TimeIt Docs Spelling Fix #110407
• [3.12] gh-110383 TimeIt Docs Spelling Fix (GH-110407) #110409
• [3.11] gh-110383 TimeIt Docs Spelling Fix (GH-110407) #110410
• gh-110383: Swap 'the all' -> 'all the' in socket docs #110434
• [3.12] gh-110383: Swap 'the all' -> 'all the' in socket docs (GH-110434) #110435
• [3.11] gh-110383: Swap 'the all' -> 'all the' in socket docs (GH-110434) #110436
• gh-110383: Array module docs fix #111018
• gh-110383: Added explanation about simplest regex use case for quantifiers. #111110
• [3.12] gh-110383: Added explanation about simplest regex use case for quantifiers. (GH-111110) #111204
• [3.11] gh-110383: Added explanation about simplest regex use case for quantifiers. (GH-111110) #111205
• gh-110383: Italicize variable name #111206
• [3.12] gh-110383: Italicize variable name (GH-111206) #111207
• [3.11] gh-110383: Italicize variable name (GH-111206) #111208
• gh-110383: Changed the doc for str.rsplit from 'starting from the left' to 'starting from the right'  #111247
• gh-110383: Fix documentation profile cumtime fix #112221
• [3.12] gh-110383: Fix documentation profile cumtime fix (GH-112221) #112262
• [3.11] gh-110383: Fix documentation profile cumtime fix (GH-112221) #112263
• gh-110383: Explained which error message is generated when there is an unhandled exception #111574
• [3.12] gh-110383: Explained which error message is generated when there is an unhandled exception (GH-111574) #112264
• [3.11] gh-110383: Explained which error message is generated when there is an unhandled exception (GH-111574) #112265
• gh-110383: Add documentation entry for sorted(d) #112777
• gh-110383: Remove references to removed popen[234] #112783
• gh-110383: Fix docstring for str.rsplit maxsplit param to 'starting from the right' #113353
• gh-110383: Improve accuracy of str.split() and str.rsplit() docstrings #113355
• [3.12] gh-110383: Improve accuracy of str.split() and str.rsplit() docstrings (GH-113355) #113379
• [3.11] gh-110383: Improve accuracy of str.split() and str.rsplit() docstrings (GH-113355) #113380
• gh-110383: Added explanation in Doc about array data types range. Based on GNU docs #113708
• gh-110383: Fix problems in Python Input and Output tutorial #118970
• gh-110383: Document socket.makefile() accepts combined modes #119150
• GH-110383: Improve Tutorial for Input Ouput #119230
• [3.13] gh-110383: Document socket.makefile() accepts combined modes (GH-119150) #119324
• [3.12] gh-110383: Document socket.makefile() accepts combined modes (GH-119150) #119325
• [3.13] GH-110383: Improve Tutorial for Input Ouput (GH-119230) #119326
• [3.12] GH-110383: Improve Tutorial for Input Ouput (GH-119230) #119327
• gh-110383: Update dict get, fromkeys, and setdefault signatures in docs #119330
• [3.13] gh-110383: Align dict.get(), .fromkeys(), and .setdefault() docs with docstrings (GH-119330) #119370
• [3.12] gh-110383: Align dict.get(), .fromkeys(), and .setdefault() docs with docstrings (GH-119330) #119371
• gh-110383: Clarify "non-integral" wording in pow() docs #119688
• [3.13] gh-110383: Clarify "non-integral" wording in pow() docs (GH-119688) #120206
• [3.12] gh-110383: Clarify "non-integral" wording in pow() docs (GH-119688) #120207
• gh-110383: Improve 'old string formatting' text in tutorial #120219
• [3.13] gh-110383: Improve 'old string formatting' text in tutorial (GH-120219) #120229
• [3.12] gh-110383: Improve 'old string formatting' text in tutorial (GH-120219) #120230

[erlend-aasland]

I'm not sure where these colours are defined.

Me neither, but ISTM the PDFs are generated from make -C Doc dist. I'm suspecting it might be the Sphinx LaTeX package sphinx.sty.

[erlend-aasland]

@encukou: I suggest creating separate, and more actionable, issues of the EPUB and PDF readability reports. I think the two remaining issues reports by Stiller are non-issues; the first is talking about IDLE in a tutorial that is using the REPL, and I'm not sure the remaining issue is worth trying to solve. Regarding the "UserList" issue, I have no opinion.

In the future, I think it would be better to not collect multiple unrelated reports into one issue, like it's done here; such an umbrella issue has an enormous risk of quickly turning stale. IMO, it is better for the reporters, for the triagers, and for contributors, if we break these up into single more actionable and easily triaged issues :)

[encukou]

I suggest creating separate, and more actionable, issues of the EPUB and PDF readability reports.

Please do make an issue! GitHub has a button to do that in the ⋯ menu.

IMO, it is better for the reporters, for the triagers, and for contributors, if we break these up into single more actionable and easily triaged issues

When I did that, I was too tempted to triage each of the reports, which resulted in a big backlog. Converting from email to GitHub needs to take me less than a minute; otherwise, on a busy day I'll leave it to “some day when I have time”.

[hugovk]

I think the two remaining issues reports by Stiller are non-issues; the first is talking about IDLE in a tutorial that is using the REPL, and I'm not sure the remaining issue is worth trying to solve.

I've checked these off as WONTFIX.

Regarding the "UserList" issue, I have no opinion.

Same, and no-one else has had a go, so I've checked this off as WONTFIX too.

We've got new issues for some of these things, I think we can close this issue now, thanks everyone for helping out!