Filewide metadata to modify toctree

[kovidgoyal]

I realize that it is furo's goal to separate the global toc from individual page headings and in general that's fine. However, sometimes, it is useful to be able to have the headings from a particular file appear in the global toc (left sidebar).

Currently the only way I can see of doing that is to have an top level file that has a ..toctree:: directive that refers to a lower level file in which the headings are of the appropriate level. This is burdensome in that one has to now have a placeholder top level file just in order to place the headings into the global toc.

Instead, I suggest allowing some file wide metadata to specify what level of headings in the file participate in the global toc. Something like

:global_toc_headings <start level> <depth>:

This would allow authors to insert headings into the global toc, where appropriate at a per file level of granularity.

[kovidgoyal]

Actually, never mind. It turns out I prefer having all file headings in the global toc which is easy to accomplish in conf.py even with furo.

[pradyunsg]

I am curious about what you are trying to do, and what solution you cam up with in the end.

[kovidgoyal]

I want all headings in the left side toc, for two reasons:

1. I find a hidden by default, per page, toc on the right somewhat undiscoverable.

2. I want a way for people to easily see an overview of any section, without having to navigate to it.

Having all the page headings in the left side toc, achieves those goals. In order to do it with furo, I just used this code:

def add_html_context(app: Any, pagename: str, templatename: str, context: Any, doctree: Any, *args: Any) -> None:
    if 'toctree' in context:
        # this is needed with furo to use all titles from pages
        # in the sidebar (global) toc
        original_toctee_function = context['toctree']

        def include_sub_headings(**kwargs: Any) -> Any:
            kwargs['titles_only'] = False
            return original_toctee_function(**kwargs)

        context['toctree'] = include_sub_headings

I just need to add some JS to make the sidebar scroll to the current anchor/heading and it will be perfect.

[kovidgoyal]

Added the JS as well, you can see the results at: https://sw.kovidgoyal.net/kitty/

And since I have your attention, would you be willing to add position: relative to .sidebar-scroll, it's needed to implement scrolling via JS as using scrollIntoView causes main content to scroll as well.