Add documentation warning: Don’t use torch.profiler.profile context manager around Trainer methods

[KAVYANSHTYAGI]

What does this PR do?

This PR adds a prominent documentation warning to the Trainer class docstring (and optionally Profiler docs) to alert users not to wrap Trainer.fit(), Trainer.validate(), or similar methods inside a manual torch.profiler.profile context manager.
Instead, users are advised to use the profiler argument in the Trainer constructor, which is the robust and officially supported method for profiling with Lightning.

This change aims to prevent a common source of cryptic internal errors and crashes reported by users who attempt to manually profile the Trainer, and improves developer experience by making the correct usage obvious in the docs.

Fixes #20779
(You can fill in the relevant issue if one exists, such as #16958)

This PR does not introduce any breaking changes.

Before submitting

Was this discussed/agreed via a GitHub issue?
Yes, this has been discussed in Lightning issues and user forums (see: #16958 and PyTorch #88472).

Did you read the contributor guideline, Pull Request section?

Did you make sure your PR does only one thing, instead of bundling different changes together?

Did you make sure to update the documentation with your changes? (if necessary)

Did you write any new necessary tests? (not for typos and docs)

Did you verify new and existing tests pass locally with your changes?

Did you list all the breaking changes introduced by this pull request?

Did you update the CHANGELOG? (not for typos, docs, test updates, or minor internal changes/refactors)

PR review

Anyone in the community is welcome to review the PR.
Before you start reviewing, make sure you have read the review guidelines. In short, see the following bullet-list:

Reviewer checklist

Is this pull request ready for review? (if not, please submit in draft mode)

Check that all items from Before submitting are resolved

Make sure the title is self-explanatory and the description concisely explains the PR

Add labels and milestones (and optionally projects) to the PR so it can be classified

References

PyTorch Issue #88472

Lightning Issue #16958

StackOverflow community discussion

Thanks for considering this! This documentation improvement should help prevent many user headaches and support requests.

---

📚 Documentation preview 📚: https://pytorch-lightning--20864.org.readthedocs.build/en/20864/

[Borda]

why this reference?

[KAVYANSHTYAGI]

These issues capture user reports and maintainer confirmations of the error caused by using torch.profiler.profile around Trainer methods, just supporting the reason for this doc warning.

[Borda]

Can you please elaborate on how this Bump pytest from 7.2.0 to 7.2.2 in /requirements #16958 captures the profiler's issue?

[KAVYANSHTYAGI]

Thanks for pointing out the confusion. I’ve removed the unrelated Lightning PR and forum links from the references, now only the directly relevant PyTorch issue is cited to support this documentation warning.