How to insert nodes between caption and actual table of contents in toctree?

Dear list.

I'm trying to implement a "gallery" feature based on the "toctree" directive.

I'm using a very simple extension of the "toctree" directive which
inserts a few thumbnail images before the actual table of contents.

The code is at https://github.com/spatialaudio/nbsphinx/pull/392 if
you are interested.

However, I would also like to be able to use the :caption: Option and
I would like to insert the thumbnail images *between* the caption and
the actual table of contents. As I have implemented it currently, the
thumbnail images appear above the caption ...

Here is a rendered example:
https://136-210404706-gh.circle-artifacts.com/0/html/a-normal-rst-file.html#thumbnail-galleries
(based on the branch
https://github.com/mgeier/nbsphinx/tree/gallery-with-caption).

I looked through the Sphinx code but I don't understand where and when
and how the caption text is inserted.

Can someone please tell me where the toctree caption is inserted into
the doctree and how I can insert my own content just below it?

cheers,
Matthias

Hi Matthias,

I'm still not familiar with structure of toctree. But it seem caption
is expanded in sphinx/environment/adapters/toctree.py.
So you might be able to modify the generated doctree.

I feel toctree structure is too complicated. So it is better to
refactor before adding feature. So any proposals are welcome!

Thanks,
Takeshi KOMIYA

2020年2月15日(土) 4:52 Matthias Geier <matthia...@gmail.com>:
> --
> You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+...@googlegroups.com.
> To view this discussion on the web, visit https://groups.google.com/d/msgid/sphinx-dev/CAFesC-dutagsFNNe%3DW7sOcb1qxXyMLvVQxKQzaRN3kCnUuo7NQ%40mail.gmail.com.

Thanks for the answer!
Yes, it looks like I should try to somehow intercept the call to
TocTree.resolve() in this file.

I didn't find a proper extension mechanism, though.

For now, I've monkey-patched the TocTree.resolve() method, see my
update at https://github.com/spatialaudio/nbsphinx/pull/392.

This seems to work fine.

If somebody knows a better way to do this, please let me know!
I agree that it's complicated!
But I have no idea how to make it less complicated.
I really don't understand how all those pieces work together ...

But I think I'm fine with a somewhat hacky solution using the current
structure. It's probably not worth refactoring as long as it keeps
working ...

cheers,
Matthias

> Thanks,
> Takeshi KOMIYA
>
> 2020年2月15日(土) 4:52 Matthias Geier:

Good Job! LGTM :-)

2020年2月17日(月) 20:24 Matthias Geier <matthia...@gmail.com>:
> To view this discussion on the web, visit https://groups.google.com/d/msgid/sphinx-dev/CAFesC-dVVGTVZziP_Gk3%2BMX-9%2Bh5ZQSsrGx-14RngG_vncEiGw%40mail.gmail.com.