3

I've learnt that it's possible to maintain my documentation in a modular form with parts/chapters etc. across multiple files by using the include command.

The only problem with this approach is that it effectively concatenates all included files into one big file, which means that they are no longer treated as separate pages by the Sphinx Read The Docs theme.

As a consequence of this, the documentation has very long pages that users have to scroll down, rather than short pages with previous/next buttons for navigation. I would like my documentation to have the latter structure because I think that it creates a much more comfortable user experience.

How can I preserve part/chapter structure without creating a single, long, page?

AZD
  • 279
  • 1
  • 8
  • That is what `toctree` is for. http://www.sphinx-doc.org/en/stable/markup/toctree.html – mzjn Oct 19 '17 at 09:21
  • Hi @mzjn, thanks for your comment. I've read the documentation on the `toctree` and know how to use it but I'm not sure I know what you mean when you say that 'That is what `toctree` is for'. Would you be able to elaborate on your comment in a full answer? – AZD Oct 19 '17 at 10:00
  • I don't understand what the problem is. toctree can be used to "preserve part/chapter structure without creating a single, long, page". – mzjn Oct 19 '17 at 10:16
  • Sometimes what appears obvious to oneself isn't obvious to others :) Would you be able to post an example of what you mean in a full answer? I would be hugely grateful! – AZD Oct 19 '17 at 10:41
  • I'm sorry, but I don't know what to say. I think you need to explain more clearly what the problem is. You wrote: "I've read the documentation on the toctree and know how to use it". What isn't working? – mzjn Oct 19 '17 at 11:03
  • 3
    @mzjn, what he's trying to say is, how can one have a chapter, that has subsections, each of which is in a separate file, and not have every single file appear in the top level table of contents. It is not obvious from the documentation you link to how this can be achieved, or even if it can be achieved. – crobar Mar 07 '18 at 10:21
  • 1
    What mzjn probably mean: Include directive with filenames creates a single HTML page, while toctree directive with section references in a part/chapter creating multiple HTML pages as the OP wants and not a TOC as one would guess from the name. – dlazesz Aug 29 '22 at 16:11

1 Answers1

2

Basing myself on the earlier question that you reference, I should warn you about the solution that is given there or more so about the question itself :-)

Your document did not reproduce the headings properly ("part" against "chapter") because the toctree directive considers the first heading in the included document as the "top heading" of that document. The other solution was to move the

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

part in the main file, the one with the toctree directive.

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

.. toctree::
   :maxdepth: 2

   test1
   test2

I learned about this through experience. I cannot find a proper reference about this, though.

Pierre de Buyl
  • 7,074
  • 2
  • 16
  • 22