gh-140727: Restructure profiling documentation for PEP 799

[pablogsal]

This PR restructures the profiling documentation to match the new profiling
package introduced by PEP 799.

The existing monolithic profile.rst is split into focused pages:

• profiling.rst: Entry point that helps users choose between statistical
  and deterministic profiling, with a comparison table and guidance on when to
  use each approach.

• profiling-tracing.rst: Documents the deterministic profiler (formerly
  documented under cProfile). Notes that cProfile remains as a
  backward-compatible alias.

• profiling-sampling.rst: Documents the new statistical sampling
  profiler. Includes quick examples upfront, explains the key concepts, covers
  all output formats (pstats, flamegraph, gecko, heatmap), live mode, and
  async-aware profiling. A defaults table shows what happens without any flags.

• pstats.rst: Separated out since it's used by both profiler types.

• profile.rst: Reduced to a deprecation stub with migration guidance for
  users of the pure Python profiler.

The whatsnew entry is updated to link to the new documentation and reference
profiling.tracing instead of cProfile.

• Issue: Document new profiling package and restructure the profiler docs according to PEP 799 #140727

---

📚 Documentation preview 📚: https://cpython-previews--142373.org.readthedocs.build/en/142373/library/profiling.html

[pablogsal]

Most of this PR is moving existing documentation into separate files rather than writing new content. The profiling-tracing.rst and pstats.rst pages are largely relocated from the old profile.rst, and profile.rst itself is reduced to a deprecation stub with migration guidance.

The actual new writing is in profiling-sampling.rst, which documents the new statistical sampling profiler. This is where review attention is most valuable. The profiling.rst entry point also has new prose explaining when to use each profiler type.

[gpshead]

Threading feels quite common. It feels like the option even existing implies there is some consequence of enabling it? State why someone might NOT want to sample all threads in the docs.

Perhaps out of scope for this docs PR, but do we actually want this default or should it be the opposite? Does the option then even need to exist?

[pablogsal]

Threading feels quite common. It feels like the option even existing implies there is some consequence of enabling it? State why someone might NOT want to sample all threads in the docs.
Perhaps out of scope for this docs PR, but do we actually want this default or should it be the opposite? Does the option then even need to exist?

We can discuss this elsewhere, but the reason is that is more expensive. You are basically dividing the sampling rate by the number of threads. There are also some of important optimizations if you know that you only want to sample the main thread.

This also generates a lot more data so the result files are a bit bigger. We can chat about what we think the default should be but the option should exist so people can decide to dedicate all sampling budget to the main thread if they wish. This can make a big difference.

[pablogsal]

State why someone might NOT want to sample all threads in the docs.

Good point 👍 Will do

[pablogsal]

Tachyon logo by @maigimenez ❤️ (she did the 3.11 and 3.10 cool release logos)

[hugovk]

I started adding suggestions via the GitHub UI but it was taking 4s to click the + and 6s to click "Add review comment" so I gave up and opened pablogsal#108 instead :/

[pablogsal]

I started adding suggestions via the GitHub UI but it was taking 4s to click the + and 6s to click "Add review comment" so I gave up and opened pablogsal#108 instead :/

[hugovk]

Thanks!

[pablogsal]

Thanks everyone for the review! ❤️