Как включить как внешние файлы, так и разделы из индекса в sphinx toc?

Question

Я собираю свою документацию по пакету python с помощью sphinx, но у меня возникли некоторые проблемы с добавлением в оглавление записей из других файлов в папке docs и других разделов, присутствующих в index.rst.

Этиэто содержимое моей папки с документами:

$ 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`

Вторая ссылка на вводный раздел работает, но первая, на toctreeне.

Как я могу добавить и api-ссылку, и введение в оглавление?

Answer 1

toctree записи являются именами файлов (с расширением файла или без него). Перекрестные ссылки, такие как :ref:`Introduction`, не работают.

Я предлагаю вам поместить введение в отдельный файл и добавить имя файла в toctree.