Sphinx: Split Output Html Into Smaller Pages Than Input Files

Suppose I have a Sphinx index file .. toctree:: foo bar And document foo has only one heading *** Foo *** All about foo. while bar has two *** Bar *** All about Bars. *

Solution 1:

Unfortunately, based on this answer from another question from the ReadTheDocs developers on irc they only build a single .html file at this time.

Source: https://stackoverflow.com/a/32788289/3750804

If you're looking for a tool that will give you multiple HTML files (while losing PDF build support, unfortunately) check out MkDocs, which can also host on readthedocs.org.

http://mkdocs.org

Solution 2:

It's not quite what you're after, but perhaps the ..include:: directive would work for you? I have one huge source file (from a legacy manual), and use comment bookmarks to include sections of it in smaller files, with those smaller files rendered separately to html. For example:

In myBigFile.rst:

***
Bar
***

All about Bars.

.. marker_start_here:

******
Parrot
******

All about ex-parrots.

.. marker_end_here:

Other stuff you don't want in your smaller file ...

Then in your separate file you have:

.. include:: myBigFile.rst
   :start-after: marker_start_here
   :end-before: marker_end_here

You might need to change your extension on the myBigFile if you don't want it included in toctrees etc, so you can avoid the duplicate section heading error if your included bits have automagically linked section headings.