How to include both external files and sections from the index into the sphinx toc?

Question

I am building my python package documentation with sphinx but I having some trouble to add to the table of contents both entries from other files in the docs folder and other sections present on the index.rst.

These are my docs folder contents:

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

And these are the first lines from 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`

The second reference to the introduction section works but the first, on the toctree doesn't.

How could I add both the api-reference and the introduction to the table of contents?

Answer 1

toctree entries are filenames (with or without a file extension). Cross-references such as :ref:`Introduction` do not work.

I suggest that you put the introduction in a separate file and add the filename to the toctree.