How to include table fo contents when using singlehtml build option?

1
votes

Context

I am using Sphinx to create technical documentation (not code-related). The input are several reStructuredText and SVG files. The output is created using the singlehtml builder (which is converted to PDF using weasyprint in a later step).

Problem

I would like to include a table of contents (TOC) in the final document. The default location for the TOC (sidebar) is not an option. I have to disable/hide the sidebar to generate a useful PDF.

Solutions (I have considered / tried)

  • toctree directive: Seems to only work with the sidebar, no matter what I try.
  • HTML Theming: I'm using it for styling the HTML output, but I would not know how to address the TOC issue.
  • Sphinx extensions: I wrote my own, but it's not very flexible and I'm still sure that others have already solved this problem.
  • Use latexpdf builder: Tried that and it solves the TOC problem, but it creates a few other problems and styling the document is so much easier for me using CSS.
  • Other tool than Sphinx: Is this a typical case of an XY problem? I would like to use reStructuredText and SVGs to generate a PDF, but I would be open to use something else than Sphinx.
2
python-sphinxtableofcontents
Interesting problem. If all other options don't work a last resort that should be guaranteed to work is to creating a nested list of cross-references by hand. This last option implies loosing some automation but you gain fine-tuned control of how the TOC is built and rendered. – bad_coder

2 Answers

2
votes

Use the contents directive.

Here's the directive in its simplest form:

.. contents::

Language-dependent boilerplate text will be used for the title. The English default title text is "Contents".

An explicit title may be specified:

.. contents:: Table of Contents
1
votes

As @mzjn already suspected, .. contents:: only lists the contents of the current file, but if I use .. include:: instead of .. toctree:: to include other documents, it works nevertheless. So what I'm currently using is this:

.. sectnum::
.. contents:: Table of Contents
   :depth: 2

.. include:: intro.rst
.. include:: processes.rst