Menu
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?
944
.. toctree:: :maxdepth: 2 intro strings datatypes numeric (many more documents listed here) This accomplishes two things: Tables of contents from all those documents are inserted, with a maximum depth of two, that means one nested heading. toctree directives in those documents are also taken into account.
RST is a powerful and straightforward markup language that, in combination with Sphinx, provides a wide range of facilities for intelligent and appealing documentation creation. It uses simple and implicit syntax to introduce a variety of content elements such as titles, code blocks, vertical lists, and many others.
The toctree directive should do what you want.
.. toctree::
:glob:
subdir1/*
subdir2/*
The glob * will alphabetically sort files within subdirs. 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.
67
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
