如何将索引中的外部文件和部分包含到sphinx目录中？

Question

我正在用sphinx构建python包文档，但是在将docs文件夹中的其他文件的条目和页面上的其他部分添加到目录时遇到了一些问题索引.rst. 你知道吗

以下是我的文档文件夹内容：

$ ls docs/
api_reference.rst  _build  conf.py  index.rst  make.bat  Makefile  _static  _templates

这是第一行索引.rst地址：

Welcome to SPIN's documentation!
================================

This is the Sorting Points Into Neighborhoods clustering method documentation.

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   :ref:`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. :ref:`Introduction`

介绍部分的第二个引用有效，但目录树上的第一个引用无效

如何将api引用和简介添加到目录中？你知道吗

Answer 1

^{}项是文件名（带或不带文件扩展名）。交叉引用如:ref:`Introduction`不起作用。你知道吗

我建议您将简介放在一个单独的文件中，并将文件名添加到toctree。你知道吗