GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — Doc: Add a single table as summary to math documentation by Nodd · Pull Request #125810 · python/cpython

Conversation

@Nodd

@Nodd Nodd commented Oct 21, 2024 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor

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/

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
dg-pb reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
Nodd added 2 commits October 20, 2024 19:18
@Nodd
Summary for math module with separate tables
51c9e75
@Nodd
Forgot remainder description
5cf795a
@bedevere-app bedevere-app Bot added docs Documentation in the Doc dir skip news labels Oct 21, 2024
@Nodd
Single table
d06e257
@Nodd Nodd mentioned this pull request Oct 21, 2024
Doc: Add multiple tables as summary to math documentation #125809
Closed
@Nodd Nodd changed the title Doc math monosummary Doc: Add a single table summary to math documentation Oct 21, 2024
@Nodd Nodd changed the title Doc: Add a single table summary to math documentation Doc: Add a single table as summary to math documentation Oct 21, 2024
merwok
merwok reviewed Oct 21, 2024
View reviewed changes
Comment thread Doc/library/math.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@Nodd
data instead of func
f817b9e
@hugovk hugovk added the skip issue label Oct 22, 2024
@nedbat

nedbat commented Oct 22, 2024

Copy link
Copy Markdown
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
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@Nodd

Nodd commented Oct 22, 2024

Copy link
Copy Markdown
Contributor Author

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!
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@merwok

merwok commented Oct 22, 2024

Copy link
Copy Markdown
Member

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…
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
Nodd added 2 commits October 23, 2024 00:11
@Nodd
Add arguments in the table
fb37008
@Nodd
Fix inconsistencies in pow documentation
8197fed
@Nodd

Nodd commented Oct 22, 2024

Copy link
Copy Markdown
Contributor Author

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.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@dg-pb

dg-pb commented Oct 23, 2024

Copy link
Copy Markdown
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
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
hugovk
hugovk reviewed Oct 23, 2024
View reviewed changes
Comment thread Doc/library/math.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@Nodd @hugovk
Remove full stops from the table
63ce52c 
Co-authored-by: Hugo van Kemenade <[email protected]>
skirpichev
skirpichev reviewed Oct 24, 2024
View reviewed changes
Comment thread Doc/library/math.rst


==================================================== ============================================
**Number-theoretic and representation functions**

@skirpichev skirpichev Oct 24, 2024

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@Nodd Nodd Oct 24, 2024

Copy link
Copy Markdown
Contributor Author

There was a problem hiding this comment.

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
skirpichev and willingc reacted with thumbs up emoji
All reactions
  • 👍 2 reactions
Comment thread Doc/library/math.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread Doc/library/math.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Nodd added 2 commits October 24, 2024 20:49
@Nodd
Fix math.pow link
c4a8424
@Nodd
Fix spacing
eed482a
@Nodd
Nodd marked this pull request as ready for review October 24, 2024 19:15
@bedevere-app bedevere-app Bot added the awaiting review label Oct 24, 2024
@Nodd
Merge branch 'main' into doc_math_monosummary
4c408d5
willingc
willingc approved these changes Oct 31, 2024
View reviewed changes

@willingc willingc left a comment

Copy link
Copy Markdown
Contributor

There was a problem hiding this 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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@bedevere-app bedevere-app Bot added awaiting merge and removed awaiting review labels Oct 31, 2024
@Nodd

Nodd commented Oct 31, 2024

Copy link
Copy Markdown
Contributor Author

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
All reactions
  • ❤️ 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
picnixz
picnixz approved these changes Nov 1, 2024
View reviewed changes

@picnixz picnixz left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this 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 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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@skirpichev

skirpichev commented Nov 1, 2024

Copy link
Copy Markdown
Member

@picnixz, see also #125810 (comment)
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@willingc

willingc commented Nov 1, 2024

Copy link
Copy Markdown
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
All reactions
  • 👍 2 reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@willingc willingc added needs backport to 3.12 only security fixes needs backport to 3.13 only security fixes labels Nov 1, 2024
@willingc
willingc merged commit 74cf596 into python:main Nov 1, 2024
@miss-islington-app

miss-islington-app Bot commented Nov 1, 2024

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the awaiting merge label Nov 1, 2024
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Nov 1, 2024
@Nodd @hugovk @miss-islington
Doc: Add a single table as summary to math documentation (pythonGH-12…
e79e721 
…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 table

Co-authored-by: Hugo van Kemenade <[email protected]>

* Fix math.pow link

* Fix spacing

---------

(cherry picked from commit 74cf596)

Co-authored-by: Joseph Martinot-Lagarde <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Nov 1, 2024
@Nodd @hugovk @miss-islington
Doc: Add a single table as summary to math documentation (pythonGH-12…
de4ebae 
…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 table

Co-authored-by: Hugo van Kemenade <[email protected]>

* Fix math.pow link

* Fix spacing

---------

(cherry picked from commit 74cf596)

Co-authored-by: Joseph Martinot-Lagarde <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
@bedevere-app

bedevere-app Bot commented Nov 1, 2024

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the needs backport to 3.13 only security fixes label Nov 1, 2024
@bedevere-app

bedevere-app Bot commented Nov 1, 2024

Copy link
Copy Markdown

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@bedevere-app bedevere-app Bot removed the needs backport to 3.12 only security fixes label Nov 1, 2024
willingc pushed a commit that referenced this pull request Nov 1, 2024
@miss-islington @Nodd @hugovk
[3.13] Doc: Add a single table as summary to math documentation (GH-1…
f8a9a1c 
…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 commit 74cf596)

Co-authored-by: Joseph Martinot-Lagarde <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
@Nodd
Nodd deleted the doc_math_monosummary branch November 2, 2024 15:29
This was referenced Nov 2, 2024
Doc: Reorganize math module documentation #126337
Merged
Doc: Summary table for pathlib #126342
Open
picnixz pushed a commit to picnixz/cpython that referenced this pull request Dec 8, 2024
@Nodd @hugovk @picnixz
Doc: Add a single table as summary to math documentation (pythonGH-12…
05da419 
…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 table

Co-authored-by: Hugo van Kemenade <[email protected]>

* Fix math.pow link

* Fix spacing

---------

Co-authored-by: Hugo van Kemenade <[email protected]>
ebonnal pushed a commit to ebonnal/cpython that referenced this pull request Jan 12, 2025
@Nodd @hugovk @ebonnal
Doc: Add a single table as summary to math documentation (pythonGH-12…
0a37d67 
…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 table

Co-authored-by: Hugo van Kemenade <[email protected]>

* Fix math.pow link

* Fix spacing

---------

Co-authored-by: Hugo van Kemenade <[email protected]>
@skirpichev skirpichev mentioned this pull request Mar 30, 2025
Add a single table as summary to cmath documentation #131887
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@merwok merwok merwok left review comments
@hugovk hugovk hugovk left review comments
@skirpichev skirpichev skirpichev left review comments
@willingc willingc willingc approved these changes
@picnixz picnixz picnixz approved these changes

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

docs Documentation in the Doc dir skip issue skip news

Projects

Docs PRs
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

8 participants

@Nodd @nedbat @merwok @dg-pb @skirpichev @willingc @hugovk @picnixz
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.