Doc: Add a single table as summary to math documentation

[Nodd]

This is an draft for a table summary for the math module, as discussed in discourse. This is the version with a single table, with intermediate headers.

Direct link to the page preview

There is an alternative with multiple tables

---

📚 Documentation preview 📚: https://cpython-previews--125810.org.readthedocs.build/

[nedbat]

Thanks for doing this, and linking directly to the preview.

I think the summary would be a little better if the arguments were shown, especially since sometimes a value mentioned in the summary is an argument, and sometimes a constant:

• exp(x): e raised to the power of x
• pow(x, y): x raised to the power of y

[Nodd]

I thought about that too, and I even started to implement it. It looks indeed better, but it has to be done manually, so it's a bit tedious. If someone knows a better way than this:

:func:`pow(x, y) <pow>`

I'm all ears!

[merwok]

The parens are added by a sphinx setting (wrongly, I always thought, as func() is not the same as func or func(a, b) – with marked-up doc we don’t need the parens to signify that this is a function), so maybe there is another setting to show signatures? Then again maybe not, as signatures can be quite heavy with annotations…

[Nodd]

I added the arguments. I choose to not mark default, positional-only nor keyword-only arguments in the table to keep it as light as possible.

[dg-pb]

👍

I like single table much more. For me, multiple tables take more time to focus and find what I need.

FYI, There is an open PR for string methods: https://github.com/python/cpython/pull/1709

[Nodd]

Thanks @willingc, I wasn't sure where was the best to ask for review. I'll keep it in mind for next time.

[skirpichev]

@picnixz, see also https://github.com/python/cpython/pull/125810#discussion_r1814366833

[willingc]

Folks, I'm merging this as is. Future PRs can iterate on sections and wording. Thanks!

[miss-islington-app[bot]]

Thanks @Nodd for the PR, and @willingc for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13. 🐍🍒⛏🤖

[bedevere-app[bot]]

GH-126308 is a backport of this pull request to the 3.13 branch.

[bedevere-app[bot]]

GH-126309 is a backport of this pull request to the 3.12 branch.