How to separate Sphinx chapters within a single part into different files?

Question

I'm using the wonderful Sphinx tool to create some documentation and I'm trying to keep the codebase in a modular form by separating chapters of the same part into separate files. (See here for definitions of 'chapter' and 'part'.)

I've tried to do this using two files, test1.rst:

######
Part 1
######

*********
Chapter 1
*********

Section 1
=========
Test Content 1.

and test2.rst:

*********
Chapter 2
*********

Section 2
=========
Test Content 2.

They are included in index.rst like this:

.. toctree::
   :maxdepth: 2

   test1
   test2

However, upon build, Chapter 2 doesn't get nested within Part 1. Why is this? Is there any way of doing this without having to create a script to append them into a single file like the example below?

Example:

######
Part 1
######

*********
Chapter 1
*********

Section 1
=========
Test Content 1.

*********
Chapter 2
*********

Section 2
=========
Test Content 2.

Answer 1

It seems like the include directive is what you are looking for. The included file's content is parsed and included at the point of the directive.

test1.rst:

######
Part 1
######

*********
Chapter 1
*********

Section 1
=========
Test Content 1.

.. include:: test2.rst