Doc/help on what's possible in custom toc templates for html sidebar

[EMK]

Having a lot of trouble figuring out how to work with templates so I can customize TOCs on my sidebar. 

I found doc on Jinja syntax at http://jinja.pocoo.org/docs/dev/templates/ but I don't understand: 

1)  How to define my template name so I can reference it from conf.py in html_sidebars and make it appear in the sidebar 

2)  How do I know what affordances exist like {{ toc }} or {{ toctree() }} and what they do?

3) Are there other variables or functions that might be useful? 

For example, I see the default localtoc.html in sphinx/themes/basic/ - 

{#

    basic/localtoc.html

    ~~~~~~~~~~~~~~~~~~~

    Sphinx sidebar template: local table of contents.

    :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.

    :license: BSD, see LICENSE for details.

#}

{%- if display_toc %}

  <h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>

  {{ toc }}

{%- endif %}

So how else could I learn about the existence of "display_toc" and "master_doc" other than seeing them here? There might be more things I want to use but don't know about. 

Also what's the difference between {{ toc }} and {{ toctree() }} - I'm guessing one holds the global toc and one is local but why the () on one of them? 

(Sorry if this is obvious to Python users, I come at Sphinx from the documentation side.)

4) Is there a variable I could use to only display my custom sidebar template for specific content files? 

That is, it would be awesome if this only showed up in the section that deals with the GUI settings pages, and those files follow a specific naming format. So if you're reading a page called "customization_overview.html" you don't see this toc but if you are reading "gui_set_name.html" you do see the toc?

[EMK]

On Wednesday, June 29, 2016 at 5:34:17 PM UTC-4, EMK wrote:

Having a lot of trouble figuring out how to work with templates so I can customize TOCs on my sidebar. 

I found doc on Jinja syntax at http://jinja.pocoo.org/docs/dev/templates/ but I don't understand: 

1)  How to define my template name so I can reference it from conf.py in html_sidebars and make it appear in the sidebar 

I did figure this out - it just uses the filename.

[Komiya Takeshi]

Hi,

>2)  How do I know what affordances exist like {{ toc }} or {{ toctree() }} and what they do?

>3) Are there other variables or functions that might be useful? 

Please read this page. It introduces variables and functions sphinx provides.

http://www.sphinx-doc.org/en/stable/templating.html

Unfortunately, display_toc is not introduced. But toc, toctree and master_doc are described.

>4) Is there a variable I could use to only display my custom sidebar template for specific content files? 

Maybe, pagename will help you.

http://www.sphinx-doc.org/en/stable/templating.html#pagename

Thanks,

Takeshi KOMIYA

2016年6月30日木曜日 6時34分17秒 UTC+9 EMK:

[EMK]

Ah, great, thanks! I was skimming that page but missed the parts I was confused about.