{
 "cells": [
  {
   "cell_type": "raw",
   "id": "d1454a25-eb5f-4eb3-b5fb-f1ac1f012b18",
   "metadata": {
    "editable": true,
    "raw_mimetype": "text/restructuredtext",
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "source": [
    ".. _cn-using-jupyter-notebooks:\n",
    "\n",
    "使用 Jupyter Notebooks\n",
    "================================================================================\n",
    "- :ref:`English <en-using-jupyter-notebooks>`\n",
    "- :ref:`中文 <cn-using-jupyter-notebooks>`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a58b620a-f732-4ab5-9245-6691bae91415",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "source": [
    "# Jupyter Notebook 与 DocFly 框架的高级使用技巧\n",
    "\n",
    "有关使用 nbsphinx 扩展的基本信息，请参阅[官方文档](https://nbsphinx.readthedocs.io/)。本指南重点介绍将 Jupyter Notebook 与 DocFly 框架集成用于 Sphinx 文档的高级技术。\n",
    "\n",
    "## 在 Jupyter Notebook 中使用 RestructuredText\n",
    "\n",
    "Jupyter Notebook 主要使用 Markdown，但您仍然可以通过使用原始单元格（Raw cells）在 Notebook 中使用 RestructuredText (RST) 或 Sphinx 语法：\n",
    "\n",
    "1. 创建一个新单元格并将其类型更改为\"Raw\"\n",
    "2. 点击\"COMMON TOOLS\"按钮\n",
    "3. 将\"Raw NBConvert Format\"设置为\"ReStructured Text\"\n",
    "\n",
    "## 文档标题设置\n",
    "\n",
    "当设置能被 nbsphinx 正确检测到的文档标题用于目录时，请在 Raw 单元格中使用以下模式：\n",
    "\n",
    "```\n",
    ".. _unique-reference-id:\n",
    "\n",
    "文档标题\n",
    "================================================================================\n",
    "```\n",
    "\n",
    "这个单元格在 notebook 文件中的 JSON 表示将是：\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",
    "    \"文档标题\\n\",\n",
    "    \"================================================================================\\n\",\n",
    "    \"...\"\n",
    "   ]\n",
    "  },\n",
    "```\n",
    "\n",
    "⚠️ 已知问题：自 2025 年 1 月 2 日起，nbsphinx 存在一个 bug，当使用 RestructuredText 单元格作为文档标题时，会阻止正确创建 TOC 链接。详见 [GitHub PR #834](https://github.com/spatialaudio/nbsphinx/pull/834)。\n",
    "\n",
    "## 文档交叉引用\n",
    "\n",
    "要使用 Sphinx 的 ``:ref:`` [交叉引用语法](https://www.sphinx-doc.org/en/master/usage/referencing.html#role-ref) 创建文档之间的引用：\n",
    "\n",
    "## 从其他文档引用此点：\n",
    "\n",
    "1. 在任何 RST 内容中定义一个引用点：\n",
    "\n",
    "```\n",
    ".. _unique-ref-link:\n",
    "\n",
    "任何内容\n",
    "```\n",
    "\n",
    "2. 从任何其他文档引用此点：\n",
    "\n",
    "```\n",
    "更多信息，请参见 :ref:`unique-ref-link`。\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "709e379e-4574-42d9-94e8-b9322a1e9d67",
   "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
}