21

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?

Patrick B.
  • 11,773
  • 8
  • 58
  • 101
  • Please read about for the `toctree` directive: http://www.sphinx-doc.org/en/stable/markup/toctree.html – Paebbels Jun 15 '17 at 13:33
  • It should work if you change the include directives in subindex.rst to `.. include:: /subdir1/file1.rst` and `.. include:: /subdir1/file2.rst`. – mzjn Jun 16 '17 at 10:58

1 Answers1

9

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.

Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • 5
    How to add an external directory? Like `../subdir1/*` – Anuj TBE Jun 24 '19 at 11:26
  • That'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): https://stackoverflow.com/questions/69626646/cannot-find-relative-path-to-local-file-in-restructuredtext-document-in-sphinx – Andreas L. Oct 19 '21 at 09:34