Sphinx Theming

Template Discovery

When I was redesigning this site, there were times when it wasn’t obvious to me which templates were being used to render a given page. Thankfully it’s not too hard to get Sphinx itself to tell you.

After some digging around in the source code for the HTML Builder I found the handle_page function responsible for passing the page to its corresponding template and from there it was easy enough to add a print statement with the information that I needed.

def handle_page(self, pagename: str, addctx: Dict, templatename: str = 'page.html',
                outfilename: str = None, event_arg: Any = None) -> None:
    ...

    try:
        print(f"{pagename}: {templatename}")
        output = self.templates.render(templatename, ctx)
    except UnicodeError:
        logger.warning(__("a Unicode error occurred when rendering the page %s. "
                          "Please make sure all config values that contain "
                          "non-ASCII content are Unicode strings."), pagename)

Then to determine which template was being used for a given page, I only had to find it in the build output.

Running Sphinx v4.2.0
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [dirhtml]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] blog/2021/sphinx-template-discovery
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
blog/2021/sphinx-template-discovery: page.htmllate-discovery
index: page.html. [100%] index

generating indices... genindex genindex: genindex.html
done
blog/author: catalog.html
blog/author/me: collection.html
blog/language: catalog.html
blog/language/en: collection.html
blog/archive: catalog.html
blog/2021: collection.html
blog/2020: collection.html
blog/2019: collection.html
blog/2018: collection.html
blog/tag: catalog.html
blog/tag/blogging: collection.html
blog/tag/c: collection.html
blog/tag/cli: collection.html
blog/tag/containers: collection.html
blog/tag/go: collection.html
blog/tag/graphics: collection.html
blog/tag/js: collection.html
blog/tag/lxd: collection.html
blog/tag/note-to-self: collection.html
blog/tag/programming-languages: collection.html
blog/tag/python: collection.html
blog/tag/sphinx: collection.html
blog/tag/stylo: collection.html
blog/tag/svg: collection.html
blog/tag/til: collection.html
blog/tag/tinygo: collection.html
blog/tag/vulkan: collection.html
blog/tag/wasm: collection.html
blog/tag/web: collection.html
blog: collection.html
blog/drafts: collection.html
writing additional pages... search search: search.html
done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.