The Python documentation should borrow the idea from the PHP.net

[erlendaasland (Erlend E. Aasland)]

@yt87

My preference would be numpy style (not necessarily one page per function), like here: numpy.reshape — NumPy v1.26 Manual

See the previous discussion:

Explicit parameter list in function documentation

I prefer the parameters of a function (with their documentation) to be listed explicitly in the function’s documentation. This is in contrast with man-style, which describes the positionals in prose. Compare open (what I call man-style) with numpy.linalg.norm (what I say employs an explicit list). I think it’s more than a preference however: I think the available parameters are easier to identify, and typing is obvious. It also reduces the mixing of parameters with side-effects and further fun…

Since that discussion, many functions and methods with lots of arguments have been converted to use this “param list” style^{[1][2][3][4][5][6][7][8]}, and more will probably follow.

If you spot a good candidate for the param list markup, feel free to submit a PR

---

1. sqlite3.connect() ↩︎

2. dbm.open() ↩︎

3. eval() ↩︎

4. ftplib.FTP() ↩︎

5. logging.Formatter() ↩︎

6. multiprocessing.shared_memory.SharedMemory() ↩︎

7. turtle.write() ↩︎

8. typing.dataclass_transform() ↩︎