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: #1709

[skirpichev]

I think this should be split out.

For some inspiration you could take look on the C17 and sections in the Annex F.10, e.g. here: https://en.cppreference.com/w/c/numeric/math. So, we should have something like 1) "Floating-point manipulation functions", 2) "Classification and comparison", 3) "Nearest integer operations", 4) "Basic operations" (maybe prod/fsum/etc - should be here).

Number-theoretic/combinatorial functions deserve a separate section.

[Nodd]

Thank you for your suggestion. I simply used the current organization of the page, and copied the existing section labels in the page. I think that reorganizing the whole page can be made in another PR, to focus this one on adding the table. I can do it afterwards.

[willingc]

This looks like a nice improvement to the docs as written. My recommendation would be to merge. If necessary, we can iterate on future PRs.

Thanks @Nodd for your first contribution 🎉

As an FYI, you can ask for folks to rereview here instead of discuss.python.org.

[Nodd]

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

[picnixz]

I saw that you were just re-using the same titles as the sections as well as their order so I think it's ok for this PR. However, in a follow-up PR we should address the following:

• "Angular conversion" should be put before trigonometric functions so that trigonometric and hyperbolic ones are next to each other.
• We should say "Power, exponential and logarithmic functions" and not just "Power and logarithmic functions" because exp(x) is not a power function per se.

[skirpichev]

@picnixz, see also #125810 (comment)

[willingc]

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

[miss-islington-app]

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]

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

[bedevere-app]

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