Doc: Reorganize math module documentation

[Nodd]

Following #125810, here is a proposal to reorganize the math documentation. I took into account the comments from the previous PRs : #125810 (comment) #125810 (review) #125810 (comment) and tried to improve from here. As suggested in a comment, I used https://en.cppreference.com/w/c/numeric/math as reference.

One thing I'm not fond of is the duplication of the paragraph about the return values, now that frexp and modf are in different sections. Note that modf is also cited in another paragraph in Basic floating point operations.

Another question I have is, should the functions be listed in alphabetic order, or in a logical order ? For example, the trigonometric functions could start with sin and cos instead of acos and asin, or gcd and lcm could be listed together. Same with sqrt and cbrt.

Direct link to the updated math module documentation

---

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

[picnixz]

cc @skirpichev

[Nodd]

Thanks @picnixz for the review, I included your modifications.

[Nodd]

Since this PR touches the whole file, merging and fixing the conflict was a pain... If this new layout is fine, can it be merged before another conflict arises? 😅

[vstinner]

Overall, I like the new math doc organization. Nice work.

Special functions

I'm not sure how special are these functions. Maybe just say "Other functions"?

[picnixz]

We had a brief discussion on this in #126337 (comment) (see also https://mathworld.wolfram.com/SpecialFunction.html).

Now, not everyone knows about the "special functions" terminology which is first informal (there is no formal definition of what a "special function", it's just that we grouped some functions under the category of "Special functions") and second, it allows us to add whatever miscelleanous functions we want to add (although Sergey hinted that we probably won't add more than what the C standard does). So I think "Miscellaneous functions" or "Other functions" is also a good title.

[Nodd]

@vstinner Thank you for your kind words.

About special functions, I proposed a change, see this comment thread. I learned that those are actually special.

[Nodd]

After thinking a bit more about it, one advantage of "Special function" is that it has a meaning to the specialists, and is no less informative than "Miscellaneous functions" or "Other functions" to other people. Those titles are too generic to actually mean anything.

My initial proposal was to be explicit by using "Error and gamma functions". This title could be changed if another function is added in the future. In the end, I simply went with status quo wins.

[skirpichev]

My initial proposal was to be explicit by using "Error and gamma functions".

This is a best variant, IMO. It's aligned with the C standard.

More generic title (like "Special functions") opens also the door for enhancement requests "lets add also this and that special functions".

[Nodd]

I resolved all the conversations.

@picnixz @skirpichev There is only the remaining question about "Special functions" vs "Error and gamma functions" vs something else. Who gets to decide?

[vstinner]

LGTM.

I like the new categories. The change mostly moves functions, the few extra changes are acceptable (I recreated the PR manually to detect "extra" changes").

I'm fine with "Special functions" which is already used.

[skirpichev]

One last nitpick. Lets not move this footer.

Edit: I meant the whole footer, not just the reference to cmath.

[Nodd]

I had two things in mind when moving this block:

• I find it not easily discoverable, I wasn't expecting another general paragraph after the API listing
• In the page layout, it effectively appears in the Constants section, which I find confusing.

I propose to put it back at the end as you asked, and to create a new section named Implementation detail. That would fix both of my concerns.

[skirpichev]

I find it not easily discoverable

It a good thing.

In the page layout, it effectively appears in the Constants section, which I find confusing.

I think that it's visually distinct from the sphinx docs of constants. No need for extra section.

[picnixz]

LGTM (modulo Sergey's comment).