{
 "cells": [
  {
   "cell_type": "raw",
   "id": "d1454a25-eb5f-4eb3-b5fb-f1ac1f012b18",
   "metadata": {
    "editable": true,
    "raw_mimetype": "text/restructuredtext",
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "source": [
    ".. _en-using-jupyter-notebooks:\n",
    "\n",
    "Using Jupyter Notebooks\n",
    "================================================================================\n",
    "- :ref:`English <en-using-jupyter-notebooks>`\n",
    "- :ref:`中文 <cn-using-jupyter-notebooks>`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f89ac453-fefb-4870-880d-bf2971704206",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "source": [
    "For basic information on using nbsphinx extension, please refer to the [official documentation](https://nbsphinx.readthedocs.io/). This guide focuses on advanced techniques for integrating Jupyter Notebooks with DocFly framework for Sphinx documentation.\n",
    "\n",
    "## Using RestructuredText in Jupyter Notebooks\n",
    "\n",
    "Jupyter Notebook primarily uses Markdown, but you can still use RestructuredText (RST) or Sphinx syntax in a Notebook by using Raw cells:\n",
    "\n",
    "1. Create a new cell and change its type to \"Raw\"\n",
    "2. Click the \"COMMON TOOLS\" button\n",
    "3. Set \"Raw NBConvert Format\" to \"ReStructured Text\"\n",
    "\n",
    "## Document Title Setup\n",
    "\n",
    "When setting up a document title that can be properly detected by nbsphinx for table of contents, use this pattern in a Raw cell:\n",
    "\n",
    "```\n",
    ".. _unique-reference-id:\n",
    "\n",
    "Document Title\n",
    "================================================================================\n",
    "```\n",
    "\n",
    "The JSON representation of this cell in the notebook file will be:\n",
    "\n",
    "```json\n",
    "  {\n",
    "   \"cell_type\": \"raw\",\n",
    "   \"id\": \"d1454a25-eb5f-4eb3-b5fb-f1ac1f012b18\",\n",
    "   \"metadata\": {\n",
    "    \"editable\": true,\n",
    "    \"raw_mimetype\": \"text/restructuredtext\", // <--- mimitype\n",
    "    \"slideshow\": {\n",
    "     \"slide_type\": \"\"\n",
    "    },\n",
    "    \"tags\": []\n",
    "   },\n",
    "   \"source\": [\n",
    "    \".. _unique-reference-id:\\n\",\n",
    "    \"\\n\",\n",
    "    \"Document Title\\n\",\n",
    "    \"================================================================================\\n\",\n",
    "    \"...\"\n",
    "   ]\n",
    "  },\n",
    "```\n",
    "\n",
    "⚠️ Known Issue: Since January 2, 2025, nbsphinx has a bug that prevents proper TOC link creation for Jupyter Notebooks when using RestructuredText cells as document titles. See [GitHub PR #834](https://github.com/spatialaudio/nbsphinx/pull/834) for details.\n",
    "\n",
    "## Cross-Referencing Documents\n",
    "\n",
    "To create references between documents using Sphinx's ``:ref:`` [cross reference syntax](https://www.sphinx-doc.org/en/master/usage/referencing.html#role-ref):\n",
    "\n",
    "## Reference this point from any other document:\n",
    "\n",
    "1. Define a reference point in any RST content:\n",
    "\n",
    "```\n",
    ".. _unique-ref-link:\n",
    "\n",
    "Any Content\n",
    "```\n",
    "\n",
    "2. Reference this point from any other document:\n",
    "\n",
    "```\n",
    "See :ref:`unique-ref-link` for more information.\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0a97b1e5-8c87-40a4-9fea-356f3c31e5f3",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}