docs: migration guide to the latest [1/n] (#17034)

* docs: migration guide - structure

* update

* try

* ...

* 1.9

* 1.8

* 1.7

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* cleaning 1.9

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* crosslink

* ...

* placeholder

* 1.6

* placeholders

* 1.5

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* 1.4

* Apply suggestions from code review

Co-authored-by: Carlos Mocholí <carlossmocholi@gmail.com>

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Carlos Mocholí <carlossmocholi@gmail.com>

Makefile

@@ -47,8 +47,8 @@ test: clean
 	python -m coverage report
 
 docs: clean
-	pip install -e . --quiet -r requirements/app/docs.txt
-	cd docs/source-app && $(MAKE) html
+	pip install -e . --quiet -r requirements/pytorch/docs.txt
+	cd docs/source-pytorch && $(MAKE) html --jobs $(nproc)
 
 update:
 	git submodule update --init --recursive --remote

docs/source-pytorch/index.rst

@@ -155,6 +155,7 @@ Current Lightning Users
 
    starter/introduction
    starter/installation
+   upgrade/migration_guide
 
 
 .. toctree::

docs/source-pytorch/past_versions.rst

@@ -3,21 +3,24 @@ Past PyTorch Lightning versions
 
 PyTorch Lightning evolved over time. Here's the complete history of versions with links to their respective docs.
 
+TO help you with keeping up to spead, check :doc:`Migration guide <./upgrade/migration_guide>`.
 
 .. list-table:: Past versions
-   :widths: 10 50 40
+   :widths: 5 50 30 15
    :header-rows: 1
 
    * - Version
      - Title
      - Bug-fix versions
+     - Upgrade guide
 
    * - `1.9 <https://github.com/Lightning-AI/lightning/releases/tag/1.9.0>`_
      - `Stability and additional improvements <https://pytorch-lightning.readthedocs.io/en/1.9.3>`_
      - `1.9.0 <https://pytorch-lightning.readthedocs.io/en/1.9.0>`_,
        `1.9.1 <https://pytorch-lightning.readthedocs.io/en/1.9.1>`_,
        `1.9.2 <https://pytorch-lightning.readthedocs.io/en/1.9.2>`_,
        `1.9.3 <https://pytorch-lightning.readthedocs.io/en/1.9.3>`_
+     - :doc:`from 1.9 to 2.0 <upgrade/from_1_9>`
 
    * - `1.8 <https://github.com/Lightning-AI/lightning/releases/tag/1.8.0>`_
      - `Colossal-AI Strategy, Commands and Secrets for Apps, FSDP Improvements and More! <https://pytorch-lightning.readthedocs.io/en/1.8.6>`_
@@ -28,6 +31,7 @@ PyTorch Lightning evolved over time. Here's the complete history of versions wit
        `1.8.4 <https://pytorch-lightning.readthedocs.io/en/1.8.4>`_,
        `1.8.5 <https://pytorch-lightning.readthedocs.io/en/1.8.5>`_,
        `1.8.6 <https://pytorch-lightning.readthedocs.io/en/1.8.6>`_
+     - :doc:`from 1.8 to 2.0 <upgrade/from_1_8>`
 
    * - `1.7 <https://github.com/Lightning-AI/lightning/releases/tag/1.7.0>`_
      - `Apple Silicon support, Native FSDP, Collaborative training, and multi-GPU support with Jupyter notebooks <https://pytorch-lightning.readthedocs.io/en/1.7.7>`_
@@ -39,6 +43,7 @@ PyTorch Lightning evolved over time. Here's the complete history of versions wit
        `1.7.5 <https://pytorch-lightning.readthedocs.io/en/1.7.5>`_,
        `1.7.6 <https://pytorch-lightning.readthedocs.io/en/1.7.6>`_,
        `1.7.7 <https://pytorch-lightning.readthedocs.io/en/1.7.7>`_
+     - :doc:`from 1.7 to 2.0 <upgrade/from_1_7>`
 
    * - `1.6 <https://github.com/Lightning-AI/lightning/releases/tag/1.6.0>`_
      - `Support Intel's Habana Accelerator, New efficient DDP strategy (Bagua), Manual Fault-tolerance, Stability and Reliability <https://pytorch-lightning.readthedocs.io/en/1.6.5>`_
@@ -48,6 +53,7 @@ PyTorch Lightning evolved over time. Here's the complete history of versions wit
        `1.6.3 <https://pytorch-lightning.readthedocs.io/en/1.6.3>`_,
        `1.6.4 <https://pytorch-lightning.readthedocs.io/en/1.6.4>`_,
        `1.6.5 <https://pytorch-lightning.readthedocs.io/en/1.6.5>`_
+     - :doc:`from 1.6 to 2.0 <upgrade/from_1_6>`
 
    * - `1.5 <https://github.com/Lightning-AI/lightning/releases/tag/1.5.0>`_
      - `LightningLite, Fault-Tolerant Training, Loop Customization, Lightning Tutorials, LightningCLI v2, RichProgressBar, CheckpointIO Plugin, and Trainer Strategy Flag <https://pytorch-lightning.readthedocs.io/en/1.5.10>`_
@@ -62,6 +68,7 @@ PyTorch Lightning evolved over time. Here's the complete history of versions wit
        `1.5.8 <https://pytorch-lightning.readthedocs.io/en/1.5.8>`_,
        `1.5.9 <https://pytorch-lightning.readthedocs.io/en/1.5.9>`_,
        `1.5.10 <https://pytorch-lightning.readthedocs.io/en/1.5.10>`_
+     - :doc:`from 1.5 to 2.0 <upgrade/from_1_5>`
 
    * - `1.4 <https://github.com/Lightning-AI/lightning/releases/tag/1.4.0>`_
      - `TPU Pod Training, IPU Accelerator, DeepSpeed Infinity, Fully Sharded Data Parallel <https://pytorch-lightning.readthedocs.io/en/1.4.9>`_
@@ -75,6 +82,7 @@ PyTorch Lightning evolved over time. Here's the complete history of versions wit
        `1.4.7 <https://pytorch-lightning.readthedocs.io/en/1.4.7>`_,
        `1.4.8 <https://pytorch-lightning.readthedocs.io/en/1.4.8>`_,
        `1.4.9 <https://pytorch-lightning.readthedocs.io/en/1.4.9>`_
+     - :doc:`from 1.4 to 2.0 <upgrade/from_1_4>`
 
    * - `1.3 <https://github.com/Lightning-AI/lightning/releases/tag/1.3.0>`_
      - `Lightning CLI, PyTorch Profiler, Improved Early Stopping <https://pytorch-lightning.readthedocs.io/en/1.3.8>`_
@@ -87,6 +95,7 @@ PyTorch Lightning evolved over time. Here's the complete history of versions wit
        `1.3.6 <https://pytorch-lightning.readthedocs.io/en/1.3.6>`_,
        `1.3.7 <https://pytorch-lightning.readthedocs.io/en/1.3.7>`_,
        `1.3.8 <https://pytorch-lightning.readthedocs.io/en/1.3.8>`_
+     -
 
    * - `1.2 <https://github.com/Lightning-AI/lightning/releases/tag/1.2.0>`_
      - `Pruning & Quantization & SWA <https://pytorch-lightning.readthedocs.io/en/1.2.10>`_
@@ -101,6 +110,7 @@ PyTorch Lightning evolved over time. Here's the complete history of versions wit
        `1.2.8 <https://pytorch-lightning.readthedocs.io/en/1.2.8>`_,
        `1.2.9 <https://pytorch-lightning.readthedocs.io/en/1.2.9>`_,
        `1.2.10 <https://pytorch-lightning.readthedocs.io/en/1.2.10>`_
+     -
 
    * - `1.1 <https://github.com/Lightning-AI/lightning/releases/tag/1.1.0>`_
      - `Model Parallelism Training and More Logging Options <https://pytorch-lightning.readthedocs.io/en/1.1.8>`_
@@ -113,6 +123,7 @@ PyTorch Lightning evolved over time. Here's the complete history of versions wit
        `1.1.6 <https://pytorch-lightning.readthedocs.io/en/1.1.6>`_,
        `1.1.7 <https://pytorch-lightning.readthedocs.io/en/1.1.7>`_,
        `1.1.8 <https://pytorch-lightning.readthedocs.io/en/1.1.8>`_
+     -
 
    * - `1.0 <https://github.com/Lightning-AI/lightning/releases/tag/1.0.0>`_
      - `General availability <https://pytorch-lightning.readthedocs.io/en/1.0.8>`_
@@ -125,3 +136,4 @@ PyTorch Lightning evolved over time. Here's the complete history of versions wit
        `1.0.6 <https://pytorch-lightning.readthedocs.io/en/1.0.6>`_,
        `1.0.7 <https://pytorch-lightning.readthedocs.io/en/1.0.7>`_,
        `1.0.8 <https://pytorch-lightning.readthedocs.io/en/1.0.8>`_
+     -

docs/source-pytorch/upgrade/from_1_4.rst

@@ -0,0 +1,36 @@
+:orphan:
+
+.. include:: link_refs.rst
+
+Upgrade from 1.4 to the 2.0
+###########################
+
+Regular User
+************
+
+.. include:: sections/1_4_regular.rst
+.. include:: sections/1_5_regular.rst
+.. include:: sections/1_6_regular.rst
+.. include:: sections/1_7_regular.rst
+.. include:: sections/1_8_regular.rst
+.. include:: sections/1_9_regular.rst
+
+Advanced User
+*************
+
+.. include:: sections/1_4_advanced.rst
+.. include:: sections/1_5_advanced.rst
+.. include:: sections/1_6_advanced.rst
+.. include:: sections/1_7_advanced.rst
+.. include:: sections/1_8_advanced.rst
+.. include:: sections/1_9_advanced.rst
+
+Developer
+*********
+
+.. include:: sections/1_4_devel.rst
+.. include:: sections/1_5_devel.rst
+.. include:: sections/1_6_devel.rst
+.. include:: sections/1_7_devel.rst
+.. include:: sections/1_8_devel.rst
+.. include:: sections/1_9_devel.rst

docs/source-pytorch/upgrade/from_1_5.rst

@@ -0,0 +1,33 @@
+:orphan:
+
+.. include:: link_refs.rst
+
+Upgrade from 1.5 to the 2.0
+###########################
+
+Regular User
+************
+
+.. include:: sections/1_5_regular.rst
+.. include:: sections/1_6_regular.rst
+.. include:: sections/1_7_regular.rst
+.. include:: sections/1_8_regular.rst
+.. include:: sections/1_9_regular.rst
+
+Advanced User
+*************
+
+.. include:: sections/1_5_advanced.rst
+.. include:: sections/1_6_advanced.rst
+.. include:: sections/1_7_advanced.rst
+.. include:: sections/1_8_advanced.rst
+.. include:: sections/1_9_advanced.rst
+
+Developer
+*********
+
+.. include:: sections/1_5_devel.rst
+.. include:: sections/1_6_devel.rst
+.. include:: sections/1_7_devel.rst
+.. include:: sections/1_8_devel.rst
+.. include:: sections/1_9_devel.rst

docs/source-pytorch/upgrade/from_1_6.rst

@@ -0,0 +1,30 @@
+:orphan:
+
+.. include:: link_refs.rst
+
+Upgrade from 1.6 to the 2.0
+###########################
+
+Regular User
+************
+
+.. include:: sections/1_6_regular.rst
+.. include:: sections/1_7_regular.rst
+.. include:: sections/1_8_regular.rst
+.. include:: sections/1_9_regular.rst
+
+Advanced User
+*************
+
+.. include:: sections/1_6_advanced.rst
+.. include:: sections/1_7_advanced.rst
+.. include:: sections/1_8_advanced.rst
+.. include:: sections/1_9_advanced.rst
+
+Developer
+*********
+
+.. include:: sections/1_6_devel.rst
+.. include:: sections/1_7_devel.rst
+.. include:: sections/1_8_devel.rst
+.. include:: sections/1_9_devel.rst

docs/source-pytorch/upgrade/from_1_7.rst

@@ -0,0 +1,27 @@
+:orphan:
+
+.. include:: link_refs.rst
+
+Upgrade from 1.7 to the 2.0
+###########################
+
+Regular User
+************
+
+.. include:: sections/1_7_regular.rst
+.. include:: sections/1_8_regular.rst
+.. include:: sections/1_9_regular.rst
+
+Advanced User
+*************
+
+.. include:: sections/1_7_advanced.rst
+.. include:: sections/1_8_advanced.rst
+.. include:: sections/1_9_advanced.rst
+
+Developer
+*********
+
+.. include:: sections/1_7_devel.rst
+.. include:: sections/1_8_devel.rst
+.. include:: sections/1_9_devel.rst

docs/source-pytorch/upgrade/from_1_8.rst

@@ -0,0 +1,24 @@
+:orphan:
+
+.. include:: link_refs.rst
+
+Upgrade from 1.8 to the 2.0
+###########################
+
+Regular User
+************
+
+.. include:: sections/1_8_regular.rst
+.. include:: sections/1_9_regular.rst
+
+Advanced User
+*************
+
+.. include:: sections/1_8_advanced.rst
+.. include:: sections/1_9_advanced.rst
+
+Developer
+*********
+
+.. include:: sections/1_8_devel.rst
+.. include:: sections/1_9_devel.rst

docs/source-pytorch/upgrade/from_1_9.rst

@@ -0,0 +1,18 @@
+:orphan:
+
+.. include:: link_refs.rst
+
+Regular User
+************
+
+.. include:: sections/1_9_regular.rst
+
+Advanced User
+*************
+
+.. include:: sections/1_9_advanced.rst
+
+Developer
+*********
+
+.. include:: sections/1_9_devel.rst

docs/source-pytorch/upgrade/link_refs.rst

@@ -0,0 +1 @@
+.. _Fabric: https://lightning.ai/docs/fabric/

docs/source-pytorch/upgrade/migration_guide.rst

@@ -0,0 +1,63 @@
+Guide how to upgrade to the 2.0 version
+#######################################
+
+The following section will guide you through updating to the 2.0 release.
+
+Particular versions
+*******************
+
+
+
+.. raw:: html
+
+    <div class="display-card-container">
+        <div class="row">
+
+.. Add callout items below this line
+
+.. displayitem::
+   :header: 1.9.x
+   :description: Upgrade from 1.9.x series to the 2.0.
+   :col_css: col-md-12
+   :button_link: 1_9.html
+   :height: 100
+
+.. displayitem::
+   :header: 1.8.x
+   :description: Upgrade from 1.8.x series to the 2.0.
+   :col_css: col-md-12
+   :button_link: 1_8.html
+   :height: 100
+
+.. displayitem::
+   :header: 1.7.x
+   :description: Upgrade from 1.7.x series to the 2.0.
+   :col_css: col-md-12
+   :button_link: 1_7.html
+   :height: 100
+
+.. displayitem::
+   :header: 1.6.x
+   :description: Upgrade from 1.6.x series to the 2.0.
+   :col_css: col-md-12
+   :button_link: 1_6.html
+   :height: 100
+
+.. displayitem::
+   :header: 1.5.x
+   :description: Upgrade from 1.5.x series to the 2.0.
+   :col_css: col-md-12
+   :button_link: 1_5.html
+   :height: 100
+
+.. displayitem::
+   :header: 1.4.x
+   :description: Upgrade from 1.4.x series to the 2.0.
+   :col_css: col-md-12
+   :button_link: 1_4.html
+   :height: 100
+
+.. raw:: html
+
+        </div>
+    </div>

docs/source-pytorch/upgrade/sections/1_4_advanced.rst

@@ -0,0 +1,35 @@
+.. list-table:: adv. user 1.4
+   :widths: 40 40 20
+   :header-rows: 1
+
+   * - If
+     - Then
+     - Ref
+
+   * - called ``ModelCheckpoint.save_function``
+     - now call ``Trainer.save_checkpoint``
+     - #7201
+
+   * - accessed the ``Trainer.running_sanity_check`` property
+     - now  access the ``Trainer.sanity_checking`` property
+     - #4945
+
+   * - used ``LightningModule.grad_norm``
+     - now use the ``pl.utilities.grad_norm`` utility function instead
+     - #7292
+
+   * - used ``TrainerTrainingTricksMixin.detect_nan_tensors``
+     - now use ``pl.utilities.grads.grad_norm``
+     - #6834
+
+   * - used ``TrainerTrainingTricksMixin.print_nan_gradients``
+     - now use ``pl.utilities.finite_checks.print_nan_gradients``
+     - #6834
+
+   * - If you relied on ``TrainerLoggingMixin.metrics_to_scalars``
+     - now use ``pl.utilities.metrics.metrics_to_scalars``
+     - #7180
+
+   * - selected the i-th GPU with ``Trainer(gpus="i,j")``
+     - now this will set the number of GPUs, just like passing ``Trainer(devices=i)``, you can still select the specific GPU by setting the ``CUDA_VISIBLE_DEVICES=i,j`` environment variable
+     - #6388