docs: update migration guide to include TF2 invocation in TF1 summary…

… APIs (#5566)

Add instructions and example for invoking TF 2.x behaviors within TF 1.x summary API logging ops.

docs/migrate.ipynb

@@ -254,7 +254,47 @@
       "source": [
         "## Converting your code\n",
         "\n",
-        "Converting existing `tf.summary` usage to the TF 2.x API cannot be reliably automated, so the [`tf_upgrade_v2` script](https://www.tensorflow.org/guide/upgrade) just rewrites it all to `tf.compat.v1.summary`.  To migrate to TF 2.x, you'll need to adapt your code as follows:"
+        "Converting existing `tf.summary` usage to the TF 2.x API cannot be reliably automated, so the [`tf_upgrade_v2` script](https://www.tensorflow.org/guide/upgrade) just rewrites it all to `tf.compat.v1.summary` and will not enable the TF 2.x behaviors automatically."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "1972f8ff0073"
+      },
+      "source": [
+        "### Partial Migration\n",
+        "\n",
+        "To make migration to TF 2.x easier for users of model code that still depends heavily on the TF 1.x summary API logging ops like `tf.compat.v1.summary.scalar()`, it is possible to migrate only the writer APIs first, allowing for individual TF 1.x summary ops inside your model code to be fully migrated at a later point.\n",
+        "\n",
+        "To support this style of migration, <a href=\"https://www.tensorflow.org/api_docs/python/tf/compat/v1/summary\"><code>tf.compat.v1.summary</code></a> will automatically forward to their TF 2.x equivalents under the following conditions:\n",
+        "\n",
+        " - The outermost context is eager mode\n",
+        " - A default TF 2.x summary writer has been set\n",
+        " - A non-empty value for step has been set for the writer (using <a href=\"https://www.tensorflow.org/api_docs/python/tf/summary/SummaryWriter#as_default\"><code>tf.summary.SummaryWriter.as_default</code></a>, <a href=\"https://www.tensorflow.org/api_docs/python/tf/summary/experimental/set_step\"><code>tf.summary.experimental.set_step</code></a>, or alternatively <a href=\"https://www.tensorflow.org/api_docs/python/tf/compat/v1/train/create_global_step\"><code>tf.compat.v1.train.create_global_step</code></a>)\n",
+        "\n",
+        "Note that when TF 2.x summary implementation is invoked, the return value will be an empty bytestring tensor, to avoid duplicate summary writing. Additionally, the input argument forwarding is best-effort and not all arguments will be preserved (for instance `family` argument will be supported whereas `collections` will be removed).\n",
+        "\n",
+        "Example to invoke <a href=\"https://www.tensorflow.org/api_docs/python/tf/summary/scalar\"><code>tf.summary.scalar</code></a> behaviors in <a href=\"https://www.tensorflow.org/api_docs/python/tf/compat/v1/summary/scalar\"><code>tf.compat.v1.summary.scalar</code></a>:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "6457297c0b9d"
+      },
+      "outputs": [],
+      "source": [
+        "# Enable eager execution.\n",
+        "tf.compat.v1.enable_v2_behavior()\n",
+        "\n",
+        "# A default TF 2.x summary writer is available.\n",
+        "writer = tf.summary.create_file_writer(\"/tmp/mylogs/enable_v2_in_v1\")\n",
+        "# A step is set for the writer.\n",
+        "with writer.as_default(step=0):\n",
+        "  # Below invokes `tf.summary.scalar`, and the return value is an empty bytestring.\n",
+        "  tf.compat.v1.summary.scalar('float', tf.constant(1.0), family=\"family\")"
       ]
     },
     {
@@ -263,6 +303,10 @@
         "id": "Pq4Fy1bSUdrZ"
       },
       "source": [
+        "### Full Migration\n",
+        "\n",
+        "To fully migrate to TF 2.x, you'll need to adapt your code as follows:\n",
+        "\n",
         "1.  A default writer set via `.as_default()` must be present to use summary ops\n",
         "\n",
         "    -   This means executing ops eagerly or using ops in graph construction\n",