add reference to myst redirect in notebook (#127)

scverse · Dec 10, 2022 · ed5d639 · ed5d639
1 parent c96cada
commit ed5d639
Show file tree

Hide file tree

Showing 2 changed files with 27 additions and 3 deletions.
diff --git a/{{cookiecutter.project_name}}/docs/conf.py b/{{cookiecutter.project_name}}/docs/conf.py
@@ -91,7 +91,6 @@
     "numpy": ("https://numpy.org/doc/stable/", None),
 }
 
-
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.

diff --git a/{{cookiecutter.project_name}}/docs/notebooks/example.ipynb b/{{cookiecutter.project_name}}/docs/notebooks/example.ipynb
@@ -27,6 +27,26 @@
     "adata = AnnData(np.random.normal(size=(20, 10)))"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "With myst it is possible to link in the text cell of a notebook such as this one the documentation of a function or a class.\n",
+    "\n",
+    "Let's take as an example the function {func}`{{cookiecutter.package_name}}.pp.basic_preproc`. \n",
+    "You can see that by clicking on the text, the link redirects to the API documentation of the function. \n",
+    "Check the raw markdown of this cell to understand how this is specified.\n",
+    "\n",
+    "This works also for any package listed by `intersphinx`. Go to `docs/conf.py` and look for the `intersphinx_mapping` variable. \n",
+    "There, you will see a list of packages (that this package is dependent on) for which this functionality is supported. \n",
+    "\n",
+    "For instance, we can link to the class {class}`anndata.AnnData`, to the attribute {attr}`anndata.AnnData.obs` or the method {meth}`anndata.AnnData.write`.\n",
+    "\n",
+    "Again, check the raw markdown of this cell to see how each of these links are specified.\n",
+    "\n",
+    "You can read more about this in the [intersphinx page](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) and the [myst page](https://myst-parser.readthedocs.io/en/v0.15.1/syntax/syntax.html#roles-an-in-line-extension-point)."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 3,
@@ -57,7 +77,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3.9.12 ('squidpy39')",
    "language": "python",
    "name": "python3"
   },
@@ -71,7 +91,12 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.13"
+   "version": "3.9.12"
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "ae6466e8d4f517858789b5c9e8f0ed238fb8964458a36305fca7bddc149e9c64"
+   }
   }
  },
  "nbformat": 4,