Author amaajemyfren
Recipients amaajemyfren, docs@python, eric.smith, ezio.melotti, gvanrossum
Date 2020-08-06.04:15:40
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1596687343.07.0.200911572997.issue41411@roundup.psfhosted.org>
In-reply-to
Content
Hi,

>The online docs seem updated, so I'm not sure why it's not working. Maybe you could try

So it seems that the .. index::[0] directive creates an index[1]. Both f-index and findex are available in it.
Search is a bit different. A searchindex[2] is generated once when the html is being created. This is then used, locally, when user does search. Still it is not very good. Multiple word queries[3] and hyphenated words don't appear to work[4] well (I also tested this locally, f-string does not get searchindexed while fstring does. Searching also gives the lexical analysis as one of the pages when searching for fstring.)


> 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;

introduction.rst has a reference to "Formatted string literals" in the "See also:" box[5]. But I can still put an example here. Should we put both str.format() and f-strings, or make this exclusively for f-strings?

> * once all this is done, update all links to point to the appropriate sections and cross-link all related sections;

Ok.

Please can we progress as follows: (Each as sequential and independent PR)

1) f-string added to stdtypes.rst. I have done this in PR 21552. We can complete that one and commit it as the first step. It provides both the f-string and the f-string-specific quacks.
2) Add the same wording of f-string to pydoc. I have been studying how to do this. At this moment help(fstring) and help(f-string) do not work.

PS C:\> py -3.9
Python 3.9.0b5 (tags/v3.9.0b5:8ad7d50, Jul 20 2020, 18:35:09) [MSC v.1924 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> help(fstring)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'fstring' is not defined
>>> help(f-string)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'f' is not defined
>>>

3) Move "Format String Syntax", "Format Specification Mini-Language", "Format examples" sections from string.rst to stdtypes.rst and ensure references all work well.

4) Add additional f-string-quarks as we discuss into stdtypes.rst.


[0] https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#index-generating-markup
[1] https://docs.python.org/dev/genindex-F.html
[2] https://docs.python.org/dev/searchindex.js
[3] https://github.com/sphinx-doc/sphinx/issues/1486
[4] https://github.com/sphinx-doc/sphinx/issues/1486#issuecomment-122115215
[5] https://docs.python.org/3.9/tutorial/introduction.html
History
Date User Action Args
2020-08-06 04:15:43amaajemyfrensetrecipients: + amaajemyfren, gvanrossum, eric.smith, ezio.melotti, docs@python
2020-08-06 04:15:43amaajemyfrensetmessageid: <1596687343.07.0.200911572997.issue41411@roundup.psfhosted.org>
2020-08-06 04:15:43amaajemyfrenlinkissue41411 messages
2020-08-06 04:15:40amaajemyfrencreate