Sphinx目录如何同时添加外部文件与index.rst章节？

我来帮你搞定这个Sphinx目录的问题~ 你遇到的核心问题是：`toctree`不支持直接用`:ref:`Introduction``这种引用语法，它需要的是文件路径或者正确的内部章节引用格式。下面给你两种可行的解决方案：

方案一：把Introduction拆成独立文件（推荐，符合Sphinx最佳实践） #

这种方式会让你的文档结构更清晰，后期维护也更方便：

1. 在docs/文件夹里新建一个introduction.rst文件，把原来index.rst里Introduction的内容挪进去：

   Introduction
   ============
   Sorting Points Into Neighborhoods, aka SPIN, is clustering technique that only relies on the data and does not map any function on the original space of the data points.
   

2. 修改index.rst里的toctree部分，直接添加introduction和api_reference两个条目：

   Welcome to SPIN's documentation!
   ================================
   This is the Sorting Points Into Neighborhoods clustering method documentation.
   
   .. toctree::
       :maxdepth: 2
       :caption: Contents:
   
       introduction
       api_reference
   

3. 如果还需要在文档内部引用Introduction章节，保留原来的:ref:introduction``就行——记得把.. _introduction:这个标签放到introduction.rst的开头，或者留在index.rst里也可以，只要路径对应上就没问题。

方案二：不拆分文件，直接在index.rst里把Introduction加入目录 #

要是不想拆文件，也可以这么改：

1. 你已经给Introduction加了.. _introduction:标签，这步没问题，保留它。
2. 修改toctree的条目，要么直接写章节标题（加* 前缀），要么直接用标签名：
   写法一（用章节标题）：

   Welcome to SPIN's documentation!
   ================================
   This is the Sorting Points Into Neighborhoods clustering method documentation.
   
   .. toctree::
       :maxdepth: 2
       :caption: Contents:
   
       * Introduction
       api_reference
   
   .. _introduction:
   Introduction
   ============
   Sorting Points Into Neighborhoods, aka SPIN, is clustering technique that only relies on the data and does not map any function on the original space of the data points.
   

   写法二（用标签名）：

   Welcome to SPIN's documentation!
   ================================
   This is the Sorting Points Into Neighborhoods clustering method documentation.
   
   .. toctree::
       :maxdepth: 2
       :caption: Contents:
   
       introduction
       api_reference
   
   .. _introduction:
   Introduction
   ============
   Sorting Points Into Neighborhoods, aka SPIN, is clustering technique that only relies on the data and does not map any function on the original space of the data points.
   

改完之后，运行make html（或者用sphinx-build -b html docs docs/_build/html命令），打开生成的_build/html/index.html，就能看到目录里同时有Introduction和API Reference的条目，点击都能正常跳转啦~

内容的提问来源于stack exchange，提问作者Otávio Vasques