Support customization of all html templates

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.

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?

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.

That makes sense.