Global table of contents

[lancegoyke]

If this is outside the scope of django-sphinx-view, please feel free to close this.

I've been playing around with this package as a builder for fitness courses. I saw your talk, Carlton, and thought Sphinx + Django might work well for permission restricted access to courses.

For extensive online content, I find a global Table of Contents helpful in keeping the reader oriented and reminded of what they've learned already and what is still to come.

An example would be the Sphinx Book Theme, where there's a global ToC on the left and a document ToC on the right:

The local "toc" block supplied in the json output works wonders. Is there a way to render a similar toc but for the entire toctree structure? Perhaps with the "active" page tagged with a CSS class?

I could very well be missing something fundamental about the toctree directive. I've tried adding a new theme and combing through the json output, but no luck yet.

[carltongibson]

Hi @lancegoyke — you win the first not-me issue prize 🎁

The short answer will be yes we can add this.

The global toctree is generated by sphinx, so we just need to look at how/where that goes and pull it into the Django template.

As well as the Sphinx Book Theme, the Furo theme has similar (and good docs/notes.)

Totally keen to add this 😄

[carltongibson]

This looks promising: https://github.com/statease/sphinx-jsontoc-builder

• Not sure I'd want to depend on it directly
• it seems to regenerate the ToC on each page, which I wonder if is necessary 🤔
• Worth comparing the HTMLBuilder there.

But it shows the path forward.

[lancegoyke]

I am HONORED to accept this prize. I'd like to thank my parents, my friends...

Small joke.

I would be happy to try to help with this, Carlton, but I'm quite inexperienced and don't want to cause more work than is necessary! I spent a few hours today diving into that package you linked and it looks promising.

[carltongibson]

Hi @lancegoyke — I think if you just adjust the make file to use the builder from that package it would "Just Work™" — enough to get up and running with anyway, which would give time to work on templates and our own adjustments to the JSONBuilder.

I'd be interested to see how far you got. (It's something I'll play with myself, but maybe not for another month or so.)

[lancegoyke]

Hey @carltongibson — I got a second wind and some time this weekend and make some headway.

Steps

First, I copied over the files from sphinx-jsontoc-builder.

Made a new directory for extensions: /source/_extensions/

Made a new directory for the builder extension: /source/_extensions/jsontoc/

Two new files in there:

1. __init__.py — this contains the setup(app) function that Sphinx needs to recognize the extension
2. builders.py — specifies the new builder and adds "toctree" to Sphinx context dict

Then I added the new builder directory to the extensions list in conf.py: extensions = ["jsontoc"]

Sphinx will build with make jsontoc, but the build output is stored in /build/jsontoc/ and django-sphinx-view was not looking there. I had to update my urls.py to find the new build directory.

The "toctree" HTML shows up in the template context. I got it to render with {{ doc.toctree|safe }}. If the current page is visible in this toctree, it had a CSS class "current".

Overall positive. It took a while to figure out how Sphinx was recognizing it, but I think it makes sense to me now.

New Problem

I now have the global ToC rendering twice on my main index.md page:

1. {% block doc %}
2. {{ doc.toctree|safe }}

I haven't had any time to play around with that, though, gotta call it a night for now!

[carltongibson]

Hey @lancegoyke — that sounds like good progress!

This is something we're definitely going to want so I think adding a custom builder ourselves will be the way forward.
In the meantime having the third-party option work is great.

I now have the global ToC rendering twice on my main index.md

🤔 OK, so we'd need to add some page metadata: either saying "show ToC" or (maybe) selecting the template to use...

[carltongibson]

Closed by #15.

[carltongibson]

Follow-up in #17.