Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Doc: Add a single table as summary to math documentation#125810

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
willingc merged 10 commits intopython:mainfromNodd:doc_math_monosummary
Nov 1, 2024

Conversation

Nodd
Copy link
Contributor

@NoddNodd commentedOct 21, 2024•
edited
Loading

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

Direct link to the page preview

There is an alternative withmultiple tables

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

dg-pb reacted with thumbs up emoji
@bedevere-appbedevere-appbot added docsDocumentation in the Doc dir skip news labelsOct 21, 2024
@NoddNodd changed the titleDoc math monosummaryDoc: Add a single table summary to math documentationOct 21, 2024
@NoddNodd changed the titleDoc: Add a single table summary to math documentationDoc: Add a single table as summary to math documentationOct 21, 2024
@nedbat
Copy link
Member

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
Copy link
ContributorAuthor

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
Copy link
Member

The parens are added by a sphinx setting (wrongly, I always thought, asfunc() is not the same asfunc orfunc(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
Copy link
ContributorAuthor

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
Copy link
Contributor

👍

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

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
@@ -26,6 +26,92 @@ The following functions are provided by this module. Except when explicitly
noted otherwise, all return values are floats.


==================================================== ============================================
**Number-theoretic and representation functions**
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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.

Copy link
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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.

skirpichev and willingc reacted with thumbs up emoji
@NoddNodd marked this pull request as ready for reviewOctober 24, 2024 19:15
Copy link
Contributor

@willingcwillingc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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
Copy link
ContributorAuthor

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

willingc reacted with heart emoji

Copy link
Member

@picnixzpicnixz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I saw that you were just re-using the same titles as the sections as well as their order so I think it's okfor 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" becauseexp(x) is not a power function per se.

@skirpichev
Copy link
Contributor

@picnixz, see also#125810 (comment)

@willingc
Copy link
Contributor

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

picnixz and hugovk reacted with thumbs up emoji

@willingcwillingc added needs backport to 3.12only security fixes needs backport to 3.13bugs and security fixes labelsNov 1, 2024
@willingcwillingc merged commit74cf596 intopython:mainNov 1, 2024
32 checks passed
@miss-islington-app
Copy link

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull requestNov 1, 2024
…5810)* Summary for math module with separate tables* Forgot remainder description* Single table* data instead of func* Add arguments in the table* Fix inconsistencies in pow documentation* Remove full stops from the tableCo-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>* Fix math.pow link* Fix spacing---------(cherry picked from commit74cf596)Co-authored-by: Joseph Martinot-Lagarde <contrebasse@gmail.com>Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
miss-islington pushed a commit to miss-islington/cpython that referenced this pull requestNov 1, 2024
…5810)* Summary for math module with separate tables* Forgot remainder description* Single table* data instead of func* Add arguments in the table* Fix inconsistencies in pow documentation* Remove full stops from the tableCo-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>* Fix math.pow link* Fix spacing---------(cherry picked from commit74cf596)Co-authored-by: Joseph Martinot-Lagarde <contrebasse@gmail.com>Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
@bedevere-app
Copy link

GH-126308 is a backport of this pull request to the3.13 branch.

@bedevere-appbedevere-appbot removed the needs backport to 3.13bugs and security fixes labelNov 1, 2024
@bedevere-app
Copy link

GH-126309 is a backport of this pull request to the3.12 branch.

@bedevere-appbedevere-appbot removed the needs backport to 3.12only security fixes labelNov 1, 2024
willingc pushed a commit that referenced this pull requestNov 1, 2024
…25810) (GH-126308)Doc: Add a single table as summary to math documentation (GH-125810)* Summary for math module with separate tables* Forgot remainder description* Single table* data instead of func* Add arguments in the table* Fix inconsistencies in pow documentation* Remove full stops from the table* Fix math.pow link* Fix spacing---------(cherry picked from commit74cf596)Co-authored-by: Joseph Martinot-Lagarde <contrebasse@gmail.com>Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
@NoddNodd deleted the doc_math_monosummary branchNovember 2, 2024 15:29
picnixz pushed a commit to picnixz/cpython that referenced this pull requestDec 8, 2024
…5810)* Summary for math module with separate tables* Forgot remainder description* Single table* data instead of func* Add arguments in the table* Fix inconsistencies in pow documentation* Remove full stops from the tableCo-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>* Fix math.pow link* Fix spacing---------Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
ebonnal pushed a commit to ebonnal/cpython that referenced this pull requestJan 12, 2025
…5810)* Summary for math module with separate tables* Forgot remainder description* Single table* data instead of func* Add arguments in the table* Fix inconsistencies in pow documentation* Remove full stops from the tableCo-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>* Fix math.pow link* Fix spacing---------Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Sign up for freeto join this conversation on GitHub. Already have an account?Sign in to comment
Reviewers

@merwokmerwokmerwok left review comments

@hugovkhugovkhugovk left review comments

@skirpichevskirpichevskirpichev left review comments

@willingcwillingcwillingc approved these changes

@picnixzpicnixzpicnixz approved these changes

Assignees
No one assigned
Labels
docsDocumentation in the Doc dirskip issueskip news
Projects
Status: Done
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

8 participants
@Nodd@nedbat@merwok@dg-pb@skirpichev@willingc@hugovk@picnixz
[8]ページ先頭
©2009-2025 Movatter.jp