Support customization of all html templates

[Jean-Paul Calderone]

Originally reported as Twisted issue 3125:

> Pydoctor has a directory full of templates it uses to generate html output. It would be nice if these templates could be customized somehow (other than directly editing them).

[Michael Hudson-Doyle (mwhudson)]

Comments from trac:

2008-04-11 08:16:52+00:00 changed by mwh ¶

I agree with the goal, but it's pretty vague. Can you explain specific need you had that led to you opening this ticket?

2008-04-11 13:17:35+00:00 changed by exarkun ¶

Specifically, I want to include the visitor-tracking javascript that is used on the main twisted site in the generated api docs. This basically amounts to a static script tag somewhere near the end of the page.

[Michael Hudson-Doyle (mwhudson)]

I still don't really have any good ideas for how to address this. Two options that spring to mind, neither very satisfactory:

1. Allow configuration of the directory from which templates are read. This would allow any possible customization, but it's basically encouraging copy/paste/hack, and would make upgrading pydoctor trying, I suspect.

2. Allow a few carefully chosen hooks that allow inserting content at various places in the template.

Hm, after writing this, this lumbers in from the massive over-engineering department:

3. Involve XSLT somewhere.

JP, any thoughts?

[Jean-Paul Calderone (exarkun)]

The way we tried to allow customization in Mantissa is to split up template files into somewhat smallish pieces (deciding on what "small" meant on an arbitrary, subjective, case-by-case basis) and then allowed each template to be overridden separately. This reduces copy/paste/hack somewhat, although we still ended up with some instances of it.

This might just mean option 1 from above, plus a fallback for anything that's missing, and then being liberal about slicing up existing templates when it would be helpful for someone trying to customize output.

For my particular use case, I currently have modifications to common.html, index.html, nameIndex.html, problemObjects.html, and summary.html, adding the same footer to each. So, a separate footer template that I could override to include something at the end of every page pydoctor emits would satisfy this particular case.

[Michael Hudson-Doyle (mwhudson)]

That makes sense.