gh-96143: Improve perf profiler docs

[erlend-aasland]

• Add What's New
• Rewrite NEWS entry to match What's New
• Document new sys APIs
• Fix formatting here and there
• Adjust wording a few places

• Issue: Allow the linux perf profiler to see Python calls #96143

[pablogsal]

LGTM

Great work! 👍

[vstinner]

I'm confused by "compatibility mode" wording whereas the env var is called "perf support". I would prefer to say that -X perf enables support for the Linux perf tool.

"Enable" support or "Add" support, not sure which one makes more send. Technically, the option adds something ;-)

The PyConfig member, the env var and the -X option have 3 different names which also confuse me. Would it make sense to rename the -X option to -X perfsupport to make it more consistent? If yes, I would suggest doing that in a separated PR.

The name "perf" is very generic and can mean many things. A newcomer might read it as: "use -X perf to get best performance" :-)

For me, "compatibility mode" sounds like "backward compatibility mode".

[erlend-aasland]

I'm confused by "compatibility mode" wording whereas the env var is called "perf support". I would prefer to say that -X perf enables support for the Linux perf tool.

+1

I've tried to address your review comments in 9c72023, @vstinner. Are you ok with those changes?

The PyConfig member, the env var and the -X option have 3 different names which also confuse me. Would it make sense to rename the -X option to -X perfsupport to make it more consistent? If yes, I would suggest doing that in a separated PR.

+1

[gpshead]

thanks for the edits!

[bedevere-bot]

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

[vstinner]

Ezio made many interesting comments. I will wait until they are addressed to review again the PR ;-)

[erlend-aasland]

Sorry for the delay. I finally got around to try to address the review. Please take a look at the changes.

[pablogsal]

@erlend-aasland can you fix the conflicts and I will land this? Thanks!

[erlend-aasland]

@erlend-aasland can you fix the conflicts and I will land this? Thanks!

Will do! Thanks for the heads-up. I forgot about this PR :)

[pablogsal]

Thanks a lot for the fixes! ❤️

I plan to land this this week as all the feedback has been addressed but I will give some time in case someone wants to request some further changes.