Organise .rst files for sphinx?

Question

I'm putting together some user guides using Sphinx. However, there are a number of .rst files and it's getting quite difficult to keep track of them when they are all in the main folder along with index.rst.

I'd like to organize them into folders like so. But then, the make html command results in warnings saying it can't find all those .rst files tucked away within folders.

How can I organise my .rst files?

index.rst
  Docs
     new_starter.rst
     subject_guides.rst
  New starter
     first_week.rst
     second_week.rst
  Subject guides
     stress.rst
     aerodynamics.rst
     data_science.rst

Answer 1

This is mentioned in the Sphinx documentation section TOC Tree.

In your index.rst, use the toctree directive:

Project Awesome
===============

Welcome to the Project Awesome docs.

.. toctree::
   :glob:
   :maxdepth: 2

   docs/*
   new_starter/*
   subject_guides/*

The above uses "globbing", but you can explicitly order the files using their names instead of globbing.