Q:

Customize globaltoc & localtoc html rendering

I'm setting up a documentation using Sphinx.  I precise I'm really new on this lib.  
My documentation can be build with one of the default theme.  All works fine :)
Now, I would like to customize the theme.  I have updated the layout.html to follow my skin.  In this template, I include the globaltoc.html & localtoc.html.  The toc is render with toctree() & toc. 
I would like to know if there is a way to update the generated html or if I need to adapt my css to the generated html? 
Thanks! 

A:

I'm going to go out on a limb and take a guess at what you're looking for - because I think I had the same issue. 
As an example, in localtoc.html, the template looks like:
<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
    {{ toc }}
{%- endif %}

{{ toc }} is a global macro for Sphinx, and I spent about an hour digging around trying to find where it was defined with absolutely no luck.  
The caveat being, {{ toc }} renders out to something like:
<ul>
   <li>Toc Item 1</li>
   <li>Toc Item 2</li>
   <li>Toc Item 3</li>
</ul>

The issue being that if your CSS wants to treat <ul> or <li> tags by class, you have no way of easily changing them.  Ultimately I think this is a limitation of Sphinx's writers/html.py, which still does a lot of stuff by hand. 
The real solution for this is to replace (possibly builders/html.py), but definitely writers/html.py in Sphinx.  Which is a lot more effort than I wanted to expend. 
I did manage to find a couple folks who've somewhat addressed this problem, but only partially:
rst2html5, which contains an html5css3 HTMLWriter & HTMLTransformer.  and docutils-html5-writer, which, looks really nice - but is not a drop-in replacement for Sphinx due to the difference between builders/html.py and the html5 writer. 
Ultimately I came up with this solution, using jinja filters.  It's an ugly hack, but it got me past the hurdle. 
<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
   {{ toc|replace("<ul>", "<ul class=\"custom\">", 1) }}
{%- endif %}

