Connect markdown and raw cell documentation regarding sphinx roles (#631)

Author: 1kastner

doc/markdown-cells.ipynb

@@ -623,14 +623,20 @@
     "[example_python_function()](a-normal-rst-file.rst#example_python_function)\n",
     "```\n",
     "\n",
-    "This is especially useful for use with the Sphinx [autodoc](https://www.sphinx-doc.org/en/master/ext/autodoc.html) extension!"
+    "This is especially useful for use with the Sphinx [autodoc](https://www.sphinx-doc.org/en/master/ext/autodoc.html) extension!\n",
+    "\n",
+    "In some situations, you might prefer to have the default Sphinx formatting and checking in place when linking to domain objects.\n",
+    "In such a case,\n",
+    "[raw cells in \"reST\" format](raw-cells.ipynb#reST)\n",
+    "could be an alternative worthwhile considering.\n",
+    "They allow one to use any kind of Sphinx roles and directives inside a Jupyter Notebook."
    ]
   }
  ],
  "metadata": {
   "celltoolbar": "Raw Cell Format",
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -644,7 +650,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.5"
+   "version": "3.8.8"
   }
  },
  "nbformat": 4,

doc/raw-cells.ipynb

@@ -61,7 +61,11 @@
    "source": [
     "### reST\n",
     "\n",
-    "Raw cells in \"reST\" format are interpreted as reStructuredText and parsed by Sphinx. The result is visible in both HTML and LaTeX output. "
+    "Raw cells in \"reST\" format are interpreted as reStructuredText and parsed by Sphinx.\n",
+    "Thus, you can e.g. use its\n",
+    "[cross-referencing abilities](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects)\n",
+    "for automatically creating/updating links to the definition of modules, classes, functions, and similar.\n",
+    "The result is visible in both HTML and LaTeX output."
    ]
   },
   {
@@ -72,6 +76,8 @@
    "source": [
     "\"**I'm** a *raw cell* in reST_ format.\"\n",
     "\n",
+    "I can contain Sphinx roles such as a link to :func:`example_python_function`.\n",
+    "\n",
     ".. _reST: https://www.sphinx-doc.org/rest.html"
    ]
   },
@@ -152,7 +158,7 @@
  "metadata": {
   "celltoolbar": "Raw Cell Format",
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -166,7 +172,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.5.1+"
+   "version": "3.8.8"
   }
  },
  "nbformat": 4,