Can I automatically generate documentation from HTML::Template?

[toma]

I have heard that a good reason for using templates is that they can be used to automatically generate documentation. I am using HTML::Template. I use templates within templates. Some templates are used by various different scripts.

I find that it can be difficult to track down how a particular piece of HTML output was generated.

I would like to read some of that autogenerated documentation. How do I create it?

I can imagine an HTML::Template subclass creating annotated HTML which illuminates the generation process. Does such a thing exist, or is there some reason why it doesn't?

[tachyon]

You can do $t = HTML::Template->new( filename => 'file.tmpl', debug => 1  ); which will write to STDERR ie your server error logs.

[toma]

This gives me a lot of lines that look something like:

### HTML::Template Debug ### 
/home/toma/audio/dyn6/perllib/EffectBlock
/templates/Add.tmpl : line 2 : parsed VAR insig1

(newlines added)
but nothing I would consider to be documentation. Am I missing something?

[tachyon]

Probably have to hack source to take an extra options flag and print the debugging info you want I guess....

[hv]

I'm not familiar with HTML::Template, but it should be trivial, either in code (probably with a minor subclassing) or by hand, to put a marker at the beginning and end of each template:

  <!-- path/to/template -->
  ...
  <!-- /path/to/template -->

Hugo

[toma]

When I have templates within templates, this approach is not as useful as I hoped, for large documents at least.

I would prefer documentation that summarizes the hierarchical HTML structure and the variables used, perhaps even automatically generating diagrams.

It seems that most general-purpose things like this that I can easily imagine have already been written. Perhaps another templating system has such a feature? If not, I can take care of it.

[hardburn]

If I understand you correctly, you want a central repository that contains the variables used in each template file. I don't know of any current tools for this. It shouldn't be too difficult, though. HTML::Template->param() in list context returns the names of all variables in the template. This may suffice for your purposes.