Doc: Reorganize math module documentation by Nodd · Pull Request #126337 · python/cpython

Nodd · 2024-11-02T18:26:46Z

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 · 2024-11-02T23:52:16Z

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

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>

Nodd · 2024-11-06T03:00:51Z

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 · 2024-11-07T16:02:00Z

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 · 2024-11-07T16:54:19Z

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 · 2024-11-07T16:56:26Z

@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 · 2024-11-07T18:07:14Z

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 · 2024-11-08T01:32:35Z

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".

picnixz

LGTM (modulo Sergey's comment).

vstinner · 2024-11-18T07:57:57Z

Merged, thank you.

Should we backport the change to avoid merge conflicts?

skirpichev · 2024-11-18T08:05:33Z

Should we backport the change to avoid merge conflicts?

Yes, I think so. Because #125810 was backported.

miss-islington-app · 2024-11-18T08:07:33Z

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

miss-islington-app · 2024-11-18T08:07:33Z

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

miss-islington-app · 2024-11-18T08:07:53Z

Sorry, @Nodd and @vstinner, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker ce453e6c2ffda657d9d728ea6372121e8264418e 3.12

miss-islington-app · 2024-11-18T08:07:58Z

Sorry, @Nodd and @vstinner, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker ce453e6c2ffda657d9d728ea6372121e8264418e 3.13

vstinner · 2024-11-18T08:08:25Z

@Nodd: Would you mind to try to backport this change to the 3.13 branch manually? There are merge conflicts.

skirpichev · 2024-11-18T08:25:34Z

3.12 backport also fails. Its all coming from #126215.

Nodd · 2024-11-18T10:24:37Z

Weird, I thought I already rebased the PR after the other modification. I'll look into it.

vstinner · 2024-11-18T13:10:29Z

Weird, I thought I already rebased the PR after the other modification. I'll look into it.

The change is merged into the main branch. I'm asking about backporting the change to the 3.13 branch. Maybe some other doc changes were not backported to 3.13?

(cherry picked from commit ce453e6) Co-authored-by: Joseph Martinot-Lagarde <contrebasse@gmail.com> Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>

bedevere-app · 2024-11-19T02:51:54Z

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

(cherry picked from commit ce453e6) Co-authored-by: Joseph Martinot-Lagarde <contrebasse@gmail.com> Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>

skirpichev · 2024-11-19T03:09:48Z

I took liberty to do backport for 3.13.

The 3.12 backport blocked by #126309.

(cherry picked from commit ce453e6) Co-authored-by: Joseph Martinot-Lagarde <contrebasse@gmail.com> Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

Nodd · 2024-11-20T14:17:19Z

Thank you @skirpichev for the backport.

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>

bedevere-appBot added docs Documentation in the Doc dir skip news awaiting review labels Nov 2, 2024

picnixz added the skip issue label Nov 2, 2024

picnixz reviewed Nov 2, 2024
View reviewed changes

Comment threadDoc/library/math.rst Outdated
Comment threadDoc/library/math.rst Outdated

skirpichev reviewed Nov 3, 2024
View reviewed changes

Comment threadDoc/library/math.rst Outdated
Comment threadDoc/library/math.rst

skirpichev self-requested a review November 3, 2024 05:51

Noddand others added 10 commits November 6, 2024 03:36

Move trigonometric and hyperbolic functions together
844dc5e

Power, exponential and logarithmic functions
d97a345

Error and gamma functions
0862e28

fmod short description
f8378e2

Reorder documentation
462dc02

Keep "Special functions"
01ec56e

Floating point arithmetic
71afe0a
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

Fix whitespace
ab69732
Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>

Sync table names and section headers
28e687c

Fix title formatting
a983ae1

Nodd force-pushed the doc_math_organize branch from ac07e54 to a983ae1Compare November 6, 2024 02:42

Nodd marked this pull request as draft November 6, 2024 02:47

bedevere-appBot removed the awaiting review label Nov 6, 2024

Fix after merge
f831a1d

Nodd marked this pull request as ready for review November 6, 2024 02:55

bedevere-appBot added the awaiting review label Nov 6, 2024

skirpichev self-requested a review November 13, 2024 02:04

skirpichev reviewed Nov 14, 2024
View reviewed changes

Comment threadDoc/library/math.rst

picnixz approved these changes Nov 14, 2024
View reviewed changes

Implementation details back to the bottom
a45e98e

skirpichev approved these changes Nov 17, 2024
View reviewed changes

vstinner merged commit ce453e6 into python:mainNov 18, 2024

bedevere-appBot removed the awaiting merge label Nov 18, 2024

vstinner added needs backport to 3.12 only security fixes needs backport to 3.13 bugs and security fixes labels Nov 18, 2024

miss-islington-appBot assigned vstinner Nov 18, 2024

bedevere-appBot removed the needs backport to 3.13 bugs and security fixes label Nov 19, 2024

vstinner mentioned this pull request Nov 19, 2024
[3.12] Doc: Add a single table as summary to math documentation (GH-125810) #126309
Closed

ebonnal pushed a commit to ebonnal/cpython that referenced this pull request Jan 12, 2025
Doc: Reorganize math module documentation (python#126337)
7767af3
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>

hugovk removed the needs backport to 3.12 only security fixes label Mar 6, 2025

Uh oh!

Uh oh!

Conversation

Nodd commented Nov 2, 2024• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Nodd commented Nov 2, 2024

Uh oh!

Uh oh!

Uh oh!

Nodd commented Nov 6, 2024

Uh oh!

vstinner commented Nov 7, 2024

Uh oh!

picnixz commented Nov 7, 2024

Uh oh!

Nodd commented Nov 7, 2024• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Nodd commented Nov 7, 2024

Uh oh!

skirpichev commented Nov 8, 2024

Uh oh!

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

vstinner commented Nov 18, 2024

Uh oh!

skirpichev commented Nov 18, 2024

Uh oh!

miss-islington-appBot commented Nov 18, 2024

Uh oh!

miss-islington-appBot commented Nov 18, 2024

Uh oh!

miss-islington-appBot commented Nov 18, 2024

Uh oh!

miss-islington-appBot commented Nov 18, 2024

Uh oh!

vstinner commented Nov 18, 2024

Uh oh!

skirpichev commented Nov 18, 2024

Uh oh!

Nodd commented Nov 18, 2024

Uh oh!

vstinner commented Nov 18, 2024

Uh oh!

bedevere-appBot commented Nov 19, 2024

Uh oh!

skirpichev commented Nov 19, 2024

Uh oh!

Nodd commented Nov 20, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Nodd commented Nov 2, 2024•
edited
Loading

Nodd commented Nov 7, 2024•
edited
Loading