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

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.