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

【问题标题】：How to include both external files and sections from the index into the sphinx toc?如何将索引中的外部文件和部分包含到 sphinx 目录中？
【发布时间】：2020-03-05 21:51:36
【问题描述】：

我正在使用 sphinx 构建我的 python 包文档，但是我在将 docs 文件夹中其他文件的条目和 index.rst 上的其他部分中的条目添加到目录时遇到了一些麻烦。

这些是我的 docs 文件夹内容：

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

这些是 index.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-reference 和 Introduction 都添加到目录中？

【问题讨论】：

标签： python python-sphinx tableofcontents toctree

【解决方案1】：

toctree 条目是文件名（带或不带文件扩展名）。 :ref:`Introduction` 等交叉引用不起作用。

我建议你把介绍放在一个单独的文件中，并将文件名添加到toctree。

【讨论】：