Eric V. Smith <eric@trueblade.com> added the comment: I think this is an excellent idea. The main f-string docs being in a section titled "Lexical Analysis" never seemed very user-friendly. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue41411> _______________________________________

Change by Ezio Melotti <ezio.melotti@gmail.com>: ---------- keywords: +patch pull_requests: +20788 stage: needs patch -> patch review pull_request: https://github.com/python/cpython/pull/21552 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue41411> _______________________________________

Ezio Melotti <ezio.melotti@gmail.com> added the comment: HOWTOs are generally used to explain how to accomplish a certain task, so I'm not sure if they are a good fit for this situation. In the list of proposed solutions in my first message, 1-3 should be quite easy to implement. This leaves us with 4-5. To summarize what we already have (let me know if I missed anything): * string.rst[0] (the string module): String constants (string constants) Custom String Formatting (string.Formatter) Format String Syntax (explains the syntax of {...}) Format Specification Mini-Language Format examples Template strings (string.Template) Helper functions (string.capwords) * stdtypes.rst[1] (about Python builtin types): Text Sequence Type — str (short intro about str) String Methods (all the str.* methods) printf-style String Formatting (old %-formatting) * introduction.rst[2] (the string section in the tutorial) * lexical_analysis.rst[3] String and Bytes literals String literal concatenation Formatted string literals The lexical analysis is probably fine as is. The introduction in the tutorial should mention f-strings, include a couple of examples, and link to the documentation for more. The stdtypes page is already quite long and crowded, so I'm wary about adding more stuff in there. So, unless we add a separate page somewhere, the string page seems the best candidate, even if technically it should be about the string module. On top of items 1-3 of my previous message, to solve 4-5 I suggest to: 1) move the printf-style formatting section to string.rst; 2) add a section about f-strings under Format String Syntax in string.rst, focusing on differences and caveats that are unique to f-strings; 3) add some f-string-specific examples after the format examples 4) mention f-string in the string section of the tutorial, and in the text sequence type section of stdtypes.rst; The string.rst page could then look something like: String constants (string constants) Custom String Formatting (string.Formatter) Format String Syntax (explains the syntax of {...}) Format Specification Mini-Language Format examples f-strings f-strings examples printf-style String Formatting (old %-formatting) Template strings (string.Template) Helper functions (string.capwords) This should consolidate all the docs in two places: string.rst and lexical_analysis.rst (they have a different target, so the separation is ok). All other places can then refer to this. Once this is done, we can still decide to move these out of string.rst. [0]: https://docs.python.org/3/library/string.html [1]: https://docs.python.org/3/library/stdtypes.html#textseq [2]: https://docs.python.org/3/tutorial/introduction.html#strings [3]: https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-l... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue41411> _______________________________________

Change by Ama Aje My Fren <amaajemyfren@gmail.com>: ---------- pull_requests: +20825 pull_request: https://github.com/python/cpython/pull/21681 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue41411> _______________________________________

Ezio Melotti <ezio.melotti@gmail.com> added the comment: Thanks both for pointing out the additional section in inputoutput.rst that I initially missed.

I have done PR 21681 that adds index to the tutorial although searching[2][3] does not seem to be better now that the reference has an index.

The online docs seem updated, so I'm not sure why it's not working. Maybe you could try moving things around and see if you can make it work? You should be able to build the docs locally and test from there. You can also see if Sphinx raises any warning during the build process, try to move the `.. index` directive just after the section title (instead of before), or add an empty line between the list of entries and the section label (unnecessary if you move the entries after the title).

This is there[0] but it _IS_ hard to find, when you don't know it is there.

I noticed (or rather, I didn't :)!

It may not be very "introduction-y", and if you like I can make a go at trying to reword it.

I think this section is fine, the only thing that needs to be update is the link at the end of the section to point to the main f-string section that we will add elsewhere.

...

The stdtypes page is already quite long and crowded ... True. But is this wrong? In my feeling this is reference documentation. It should be accurate, complete and clear. It may not need to be "textbook-like".

You might be right.

Some thoughts: - There may be benefit in reorganising stdtypes.rst to improve the flow without changing the actual content. This could mean breaking it up into a number of documents rather than the monolith it is.

Both in the documentation and in the code, there are advantages in having everything on a single page/file (such as easier ctrl+f search) but also disadvantages. Given the goal of the page, I think keeping it monolithic is fine: it provides a summary of all the built-in types in a single place. Breaking it down into multiple pages will have other issues. If you make a page per type, you will have some pages that are very short, and it will be more difficult to get an overview of all the types, comparing them, and searching through all of them at once.

- It does feel like printf[4] was plugged in later because str.format()[5] had been explained earlier. (Although I believe printf came before str.format()). A first time reader of the document will find it hard to know the one way that is right when it comes to formatting.

If I recall correctly that section has also been there, but initially it was just describing the standard way of doing string formatting, and when str.format() was added, it got renamed and the note at the top was added to link to the str.format() documentation. I guess that the str.format documentation ended up in string.rst because it was related to string.formatter, and the author wanted to keep them together.

- f-strings should probably also be described here because it _is_ built in, no? It may not be accurate to say it is in /Lib/strings. There is no reference that a developer can just look at to remind/confirm to themselves how to "do it".

Agreed, stdtypes.rst would be the right place where to document this, my only concerns were: 1) the size of the page (that as said above, is not such a big deal); 2) keeping str.format() and string.Formatter() together (but this is also not a huge concern). Also note that str.format() is not documented in stdtypes.rst, however there is an entry for str.format() with a clear link to the formatting docs, so I never had a problem finding it, even if I needed an extra click. [...]

But now (and this is mainly to me) it appears that another problem is a need to consistently, clearly, and in one place describe the various elements/nuances/eccentricities of presenting data in Python: - string - string.Formatter, - string.Template, - str.format() - f-string - Format Specification Mini-Language - maybe even __format__ and conversion? - etc

What about doing the following: * keep having stdtypes.rst cover and explain all the built-in types and their features; * move the "Format String Syntax", "Format Specification Mini-Language", "Format examples" sections from string.rst to stdtypes.rst where they belong; * integrate f-strings in these sections, and add a new section explaining f-string-specific quirks; * leave the printf-style string formatting in stdtypes.rst, after the format sections * use string.rst to document the string module and its objects, hence leaving string.Formatter and string.Template here, where they belong (string.Formatter is self contained enough that doesn't need to be with the other format sections); * leave the inputoutput.rst and lexical_analysis pages as they are; * update the introduction.rst page to mention f-string; * once all this is done, update all links to point to the appropriate sections and cross-link all related sections;

I propose one of the following two: 1) A new section in Library documentation just to handle strings, then systematically removing them elsewhere.(Built-In Functions, Built-In Types, Text Processing Services)

Doing this would leave a gap in the built-in types page, and you would still want things things like string.Formatter and string.Template to be documented in string.rst. It also raises the question: where should we put this page?

2) We take all that Python history and explain it in a HOWTO, and add a developer friendly reference in the Library for f-string. More like Logging Cookbook rather than Logging Howto.

One of the reasons why I'm not fond of the HOWTO idea, is that these are built-in features that need to be documented in the main documentation, where the string type is documented. It is my understanding that the HOWTOs are mostly meant as standalone (and somewhat external) additions that cover a specific topic in detail. While having an HOWTO on all the quirks and options for doing string formatting in Python does make sense, we would still have to cover it in the main docs, thus ending up duplicating a lot. For example the argparse tutorial (one of the HOWTOs), shows actual examples of how to use argparse, but the module itself and its API are already extensively documented in the argparse module documentation. The only way I could see it working is if we turned the "Format Examples" section in an HOWTO and add more examples specific to f-string, however when I wrote that section I think I tried to cover all the features and the end result was compact enough to fit in a single section. I'm also not sure there's much value in adding more examples and documentation about the old string formatting, string.Formatter, and string.Template, since nowadays they are rarely used (especially the last two). There are also another couple of thoughts I had, that however I haven't fully developed yet (so it's better to deal with them later or in another issue): * str.format() is still used in a lot of places in the docs, where f-strings could be used instead. These should be updated to use f-string; * format(), str.format(), and f-string, have quite a lot of overlapping, but I'm not sure what's the best way to document them clearly without unnecessary repetition. I have a feeling that documenting the format mini-language and using f-string for the features shared by all three might be the best option -- additional examples that are specific to format(), str.format(), and f-strings, can then be added separately. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue41411> _______________________________________

Guido van Rossum <guido@python.org> added the comment: @ezio.melotti: What is this waiting for at this point? There was some good energy here but progress seems halted, waiting for some kind of decision. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue41411> _______________________________________

Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: Eric, do you want to approve and apply these PRs ? ---------- assignee: docs@python -> eric.smith nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue41411> _______________________________________