Improve and consolidate f-strings docs

[ezio-melotti]

BPO	41411
Nosy	@gvanrossum, @rhettinger, @ericvsmith, @ezio-melotti, @sblondon, @amaajemyfren
PRs	gh-85583: Document f-strings in library/stdtypes.rst #21552 gh-85583: Add f-string index in tutorial/inputoutput.rst  #21681

^{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 = 'https://github.com/ericvsmith'
closed_at = None
created_at = <Date 2020-07-27.16:31:32.992>
labels = ['type-feature', '3.8', '3.9', '3.10', 'docs']
title = 'Improve and consolidate f-strings docs'
updated_at = <Date 2021-05-02.20:18:53.236>
user = 'https://github.com/ezio-melotti'

bugs.python.org fields:

activity = <Date 2021-05-02.20:18:53.236>
actor = 'rhettinger'
assignee = 'eric.smith'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-07-27.16:31:32.992>
creator = 'ezio.melotti'
dependencies = []
files = []
hgrepos = []
issue_num = 41411
keywords = ['patch']
message_count = 12.0
messages = ['374398', '374400', '374402', '374475', '374489', '374508', '374597', '374613', '374913', '376330', '392715', '392721']
nosy_count = 7.0
nosy_names = ['gvanrossum', 'rhettinger', 'eric.smith', 'ezio.melotti', 'docs@python', 'sblondon', 'amaajemyfren']
pr_nums = ['21552', '21681']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue41411'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

Linked PRs

• [3.13] gh-85583: Add f-string index in tutorial/inputoutput.rst (GH-21681) #126191
• [3.12] gh-85583: Add f-string index in tutorial/inputoutput.rst (GH-21681) #126192
• gh-85583: Add overview of formatted string literals (f-strings) to str #132689
• [3.13] gh-85583: Add an overview of formatted string literals (f-strings) to str (GH-132689) #132767

[ezio-melotti]

[Creating a new issue from bpo-41045]

I was just just trying to link to someone the documentation for f-strings, but:

1. Searching "fstring" only returns two results about xdrlib0;
2. Searching "f-string" returns many unrelated results1;
3. The first (and closer) result (string -- Common string operations2) yields nothing while using ctrl+f with fstring, f-string, f', f";
4. at the top of that page there are two links in a "see also":

• Text Sequence Type — str3: it mentions raw strings at the beginning, but also yields no results for fstring, f-string, f', f";
• String Methods4: that is another section of the previous page (so ctrl+f doesn't find anything), but has a link to "Format String Syntax"5;

5. The "Format String Syntax" page5 has another link in the middle of a paragraph that points to "formatted string literals", that eventually brings us to the right page6;
6. the "right page"6 has a wall of text with a block of code containing the grammar, luckily followed by a few examples.

I think we should:

1. add index entries for "f-string" and "fstring" in the relevant sections of the docs, so that they appear in the search result;
2. in the Text Sequence Type — str3 section, have a bullet list for f-strings, raw-strings, and possibly u-strings;
3. possibly use the term "f-string" in addition (or instead) of "formatted string literal", to make the pages more ctrl+f-friendly throughout the docs;
4. possibly have another more newbie-friendly section on f-string (compared to the lexical analysis page) in the tutorial, in the stdtypes page7 (e.g. before the printf-style String Formatting" section8), or in the string page2 (e.g. after the "Format String Syntax" section[10]);
5. possibly reorganize and consolidate the different sections about strings, string methods, str.format(), the format mini-language, f-strings, raw/unicode-strings, %-style formatting in a single page or two (a page for the docs and one for the grammar), since it seems to me that over the years these sections got a bit scattered around as they were being added.

[ericvsmith]

I think this is an excellent idea. The main f-string docs being in a section titled "Lexical Analysis" never seemed very user-friendly.

[gvanrossum]

It's basically an accident that the only f-strings docs are in the language reference. Yes, they should be there, and the text there is pretty good for the reference, but there isn't much about them elsewhere outside of the tutorial, so everything links there. Maybe we need a section on them in the library part, of intermediate complexity between what's in the tutorial an what's in the reference. This could be on equal footing with the descriptions of % formatting and .format(), which seem to be quite extensive. We might also be able to share some text between .format() and f-strings, since the !x and :... parts are treated identically AFAICT. This would be another refactoring of some part of the docs.