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.

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

All about ex-parrots.

If I compile this to HTML, it will create three pages; index, foo and bar. But suppose I want Parrot to have its own HTML page. Is there a way to achieve this without splitting the bar source file?

回答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

回答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.

来源：https://stackoverflow.com/questions/34913006/sphinx-split-output-html-into-smaller-pages-than-input-files

标签

python-sphinx