Using javascript instead of Sphinx's default toctree

Question

I'm using sphinx to auto-generate html pages. The Table of Contents is really long so I'm trying to add a new html class (among other things) to the toctree's div so I can use a javascript library. Basically wanting to change how the toctree generates its HTML.

I've found the globaltoc.html file, put it in the _templates folder and uncommented the template_path in conf.py.

This is the file in the _templates directory.

{% extends '!globaltoc.html' %}

<div class="toctree-wrapper compound dhtmlxTree" id="toc", setImagePath="_static/imgs/csh_dhx_skyblue/">

{{ toctree() }}
</div>

If I'm doing this completely wrong please tell me another way to do this. I'd like to be able to this in pure reST, but it doesn't seem possible. I've looked at the limited examples on Sphinx templating and this is all I can find.

The overall goal of this is to use dhtmlxTree for use with a very large tree. I've already added the required .js files and .css files to layout.html. I just need the div that contains the toctree to have the class I need. I can get the results I need by editing it manually, now i need to automate it.

Thanks for your help.

Answer 1

I believe there are two possible solutions to my problem:

1. Using Jinja templates to write the javascript and the bulleted list. Currently, I'm not familiar with using the recursive Jinja flag. So this solution, while possible, may cause me more frustration than the second solution.

2. Simply reducing the :maxdepth: attribute for the toctree directive. It was set to 4. Reducing this number makes the Table of Contents smaller and therefore easier to read.

After thinking about the need to see all the layers, I realized it was just silly and it reduced the usefulness of the Table of Contents. So I just reduced the :maxdepth: to 2 and everything is back to the simplicity that reST and Sphinx offers.

Better design trumps the cool factor every time.