How to correctly include other ReST-files in a sphinx-project?
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.
Related videos on Youtube
![Patrick B.](https://i.stack.imgur.com/AQCJr.jpg?s=256&g=1)
Patrick B.
Scott Meyers: "[..] This is C++; everything is a lie but it's really close to the truth. [..]"
Updated on June 16, 2020Comments
-
Patrick B. about 4 years
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 asubindex.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 seeinginclude:: file1.rst
insidesubdir1
.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?-
Paebbels about 7 yearsPlease read about for the
toctree
directive: sphinx-doc.org/en/stable/markup/toctree.html -
mzjn about 7 yearsIt should work if you change the include directives in subindex.rst to
.. include:: /subdir1/file1.rst
and.. include:: /subdir1/file2.rst
.
-
-
Anuj TBE about 5 yearsHow to add an external directory? Like
../subdir1/*
-
Andreas L. over 2 yearsThat's exactly the issue I'm currently trying to resolve (referring to a file outside or above the root directory level of the active .rst - file): stackoverflow.com/questions/69626646/…