Ezio Melotti <ezio.melo...@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 <rep...@bugs.python.org> <https://bugs.python.org/issue41411> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
