docs: warning don’t use torch.profiler.profile context manager around Trainer methods (#20864)

* Update profiler.rst
* move documentation to basic

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Nicki Skafte Detlefsen <[email protected]>
Co-authored-by: Jirka Borovec <[email protected]>
(cherry picked from commit 04e103b)

Author: 4 people

docs/source-pytorch/tuning/profiler_basic.rst

@@ -121,3 +121,22 @@ This can be measured with the :class:`~lightning.pytorch.callbacks.device_stats_
 
 CPU metrics will be tracked by default on the CPU accelerator. To enable it for other accelerators set ``DeviceStatsMonitor(cpu_stats=True)``. To disable logging
 CPU metrics, you can specify ``DeviceStatsMonitor(cpu_stats=False)``.
+
+.. warning::
+
+    **Do not wrap** ``Trainer.fit()``, ``Trainer.validate()``, or other Trainer methods inside a manual
+    ``torch.profiler.profile`` context manager. This will cause unexpected crashes and cryptic errors due to
+    incompatibility between PyTorch Profiler's context management and Lightning's internal training loop.
+    Instead, always use the ``profiler`` argument in the ``Trainer`` constructor or the
+    :class:`~lightning.pytorch.profilers.pytorch.PyTorchProfiler` profiler class if you want to customize the profiling.
+
+    Example:
+
+    .. code-block:: python
+
+        from lightning.pytorch import Trainer
+        from lightning.pytorch.profilers import PytorchProfiler
+
+        trainer = Trainer(profiler="pytorch")
+        # or
+        trainer = Trainer(profiler=PytorchProfiler(dirpath=".", filename="perf_logs"))