My hand-written documentation/user-guide (written in ReStructuredText with sphinx) has become quite big so I started organize my .rst-files in sub-directories.
In the index.rst
I'm including a subindex.rst
of each sub-directory which itselfs includes other .rst
-files for further sub-directories.
index.rst
:
.. include:: subdir1/subindex.rst
.. include:: subdir2/subindex.rst
subdir1/subindex.rst
:
.. include:: file1.rst
.. include:: file2.rst
In principle this works well, except that sphinx is recursively looking for .rst
-files which it tries to parse. without changing the current-working dir. So, it fails when seeing include:: file1.rst
inside subdir1
.
I'm working around this issue by setting exclude_pattern
to ignore my subdirs. This seems not right.
What would be the right way to include a .rst
-file of a subdir?
The toctree directive should do what you want.
.. toctree::
:glob:
subdir1/*
subdir2/*
The glob *
will alphabetically sort files within subdir
s. To avoid sorting, you could specify the order without globbing.
.. toctree::
:maxdepth: 2
subdir1/file2
subdir1/file1
subdir2/file1
subdir2/file2
If you don't want individual pages but one huge page, you can invoke make singlehtml.