Sphinx RST expand subpages in html output

Question

I'm using the sphinx documentation system to generate reports in both HTML and Latex output formats. So have a hierarchical structure where I have a read index.rst which contains a toctree that references all chapters in order of appearance. Then a chapter is a folder which also contains an index.rst with only a header and a toctree which includes all sections for that chapter.

So as an example my structure looks likes this:

root
    - index.rst <- Contains only a toctree that references other chapters index.rst.
    - SomeChapter
        - index.rst <- Contains heading and toctree that references actual content
        - section1.rst <- actual content
        - section2.rst <- actual content
        ....

This renders beautifully with latex since you will literally get someChapter and below that the sections but in html those are all seperate pages which get's boring quick for some smaller subsections since you have to keep clicking around. Is there a way to instruct the html builder that in some cases it should show the subpages in the same page where they are in the toctree and not create subpages for it?

I know about singlehtml but that does build an entire single html page for it and I want to do it partially because a lot of times different chapters are great with different pages but sections can be easily on the same page.

Any help is appreciated.

score 0 · Answer 1 · answered Mar 22 '18 at 10:46

Untested answer.

Have two different index pages, one for HTML (index.rst) and LaTeX (indexlatex.rst), where the latter is a copy of the former, then the former gets modified.

Then in your conf.py, specify indexlatex.rst as the entry toctree. Example from Pyramid:

latex_documents = [
  ('latexindex', 'pyramid.tex',
  ...
  )

Finally to modify index.rst, you would use a series of include directives and remove the toctree directive.

.. include:: section1.rst
.. include:: section2.rst

You might also need to use :orphan: metadata on the latexindex file to suppress warnings about it not being included in the index's toctree.

Sphinx RST expand subpages in html output

1 Answers1