[New-bugs-announce] [issue29526] Documenting format() function

[Hugo Prod'homme]

New submission from Hugo Prod'homme:

Hello python contributors,
this is my first time on python.org and I am coming with a suggestion.

The idea is to help people that have to format strings containing numbers of various kinds, I am from the scientific domain but this should help everybody anyway.

In the past the strftime was the best way to format numbers in strings (truncating to some digits after point, setting to exponent notation, etc...). To remind the "strf language" one had to use the internet or a document such as this page :
<a href="http://strftime.org/">http://strftime.org/</a>

Some idea was provided to add this indications in the python docs.
<a href="http://bugs.python.org/issue9650">http://bugs.python.org/issue9650</a>

Now the format() function has appeared in the python __builtins__ and this is even more adequate to add help about the string formatting, because we can write the "Format Specification Mini-Language" directly inside the docstring of the format.__doc__ . See the paragraph named "7.1.3.1. Format Specification Mini-Language" in the following page :
<a href="https://docs.python.org/2/library/string.html">https://docs.python.org/2/library/string.html</a>

I emphasize, the interest of this is to allow the user to be reminded of the formatting options without opening another document than his(her) script, to avoid breaking the workflow.

I am providing what I think is the minimal material that the docstring should contains within the attached file. I am not really familiar with docstring formatting according to PEP (436?) and someone should help getting this in the right way of writing. Furthermore, a specific syntax  is needed within the string in addition to the format() arguments, this should be described. And the reminder about the mini-language should appear clearly as a reminder. These are two supplemental difficulties in comparison with an usual docstring.

To anyone thinking something else should be added to the docstring; please add or say it.

PS: I think I can start from the matplotlib.pyplot.plot.__doc__ as a template to complete the format.__doc__ but I have some work aside for now.

----------
files: format_docstring_v0.1.txt
messages: 287539
nosy: hugo.prodhomme at gmx.fr
priority: normal
severity: normal
status: open
title: Documenting format() function
type: enhancement
versions: Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7
Added file: http://bugs.python.org/file46625/format_docstring_v0.1.txt

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue29526>
_______________________________________