HTML Report Customization

[callendorph]

Hi,

First - this whole project is great. It took some time to get up to speed but super impressive what you have put together.

I would like to customize the output HTML report. Things I would like to do are:

1. Add a header with a logo for branding the report.
   1. I'm imagining running the simulation in a Github Action and then posting the report to a Github Pages for that project.
   2. Then the results can be viewed nicely via the CI.
2. Add a script that auto refreshes when the project builds
   1. For example, something like this: https://livejs.com/
3. Customize the CSS for the report by including files in the head section.
4. Sky is the limit honestly, I really like wavedrom for waveforms.

With the current implementation of Report2Html.tcl - I don't see a clear way to do that without modifying it and adding a bunch of code. Maybe I missed something ?

In my ideal world - I would be to keep these project specific customizations in the Parent project that is leveraging this repo as a submodule or library.

Have you considered using a template engine for generating the HTML? Coming from Python, there are several template engines for generating HTML content formats (for example, Jinja). They do a really nice job of separating out the presentation layer from the data.

I'm not an expert in TCL but google seems to indicate there are a couple of TCL-based template engine options:

1. textutil::expander
   1. Seems to already be in tcllib (I've checked it is present in tcllib v1.20 package on ubuntu 22.04)
   2. Docs seem pretty sparse to me but what do I know.
2. TemplaTCL
   1. I don't know where this is - I can't find it on github. Seems like this might just be a message board ?
   2. This would add a dependency which is probably not optimal.

Thoughts? Is this a reasonable path or have you tried this already and hic sunt dracones?

[JimLewis]

Hi Carl,
Anything that goes in the header should be straight forward to add. If you look at the top of Report2Html, the file copy below copies the file OsvvmLibraries/Scripts/summary_header_report.html to the the file FileName. Immediately after the file copy additional header information could be added. The information added could be done by searching for ReportBuildName.css (or other name) in either the ${CurrentSimulationDirectory} or in OsvvmLibraries/Scripts.

proc Report2Html {ReportFile} {
  variable ResultsFile
  variable ReportBuildName

  set ReportFileRoot  [file rootname $ReportFile]
  set ReportBuildName [file tail $ReportFileRoot]
  set FileName ${ReportFileRoot}.html
  
  set Report2HtmlDict [::yaml::yaml2dict -file ${ReportFile}]
  set ReportHeaderHtmlFile [file join ${::osvvm::OsvvmScriptDirectory} summary_header_report.html]
  file copy -force ${ReportHeaderHtmlFile} ${FileName}
  set ResultsFile [open ${FileName} a]

I am open to either collaborating or pull requests to add features such as this. We should hash through them here and perhaps prototype them (using manual edits to files) so we agree on the result.

I have not used a template engine before. Open to using one if it gets us something better than what we currently have. What is currently there is based on figuring out what I could do in the time that I had. I would need help with that.

I am on travel until July 7, so my response may be slow during this time.

Cheers,
Jim

[callendorph]

OK - I put together a very limited proof of concept here:

https://github.com/callendorph/OSVVM-Scripts/tree/issues/47_HTML_templating

With tcllib installed, you should be able to run:

tclsh ReportTemplate.tcl > report.html

Keep in mind that:

1. I'm not a TCL dev - this is the first non-trivial TCL code I've written. I'm probably not writing idiomatic TCL, I probably don't understand scoping well, and I've probably made some dumb decisions.
2. The textutil::expander works but I didn't find too many examples.
   1. I was hoping there would just be a library that already implemented templates similar to Jinja or Django's template facility. It doesn't seem like TCL has a pre-existing library of that form.
   2. Writing, debugging, testing, and maintaining a template engine using expander is probably not a trivial task.
3. File Discovery
   1. In the example, I'm just finding whatever template files are located in the current working directory
   2. I think a better model would be a project setting that provided the user the ability to set a TEMPLATE_PATH that would be searched for files matching a particular file name. Then the OSVMM-Scripts directory could be the last directory searched so that the default template would always render.
4. Errors in Templates
   1. I currently have expander configured to output an error message if there is a macro problem:

<body>
    <p> The answer is: 
=================================
*** Error in macro at line 6, column 23:
*** [var_error msg]
--> invalid command name "var_error"
=================================
 </p>
    <H1> List Example </H1>

But there are other options.

How would this work for a OSS project ?

I imagine it being something like this:

1. There is a default template, similar in kind to header_report.thtml (note the t for template), in the OSVVM-Scripts repo.
   1. This is the baseline and would get generated if the user does nothing.
2. The Report2Html.tcl changes a little
   1. Most of the content that is generated by puts $ResultsFiles "<h2>$Report..." gets moved to the template.
   2. The top level Report2Html passes a content dict to the ApplyTemplate function.
      1. It could be Report2HtmlDict directly.
      2. My guess is that there will be some intermediate values that need to be generated and added to the content dict.
   3. It would be great if the user could select via a setting or passed argument the base template file to use. Ie, instead of using header_report.thtml - it would look for user_report.thtml.
3. If a user want to modify and create custom reports:
   1. Add a directory to TEMPLATE_PATH that contains:
      1. Files of the user's custom templates.
      2. Files that have the same name as files in OSVVM-Scripts so that we can override those files.
   2. Set which base template file to use if different.

Final Thoughts

1. There are probably corner cases that I'm missing
2. This template approach expands nicely to XML and probably to Junit as well.
3. This project is likely a lot more work than I thought from the beginning because there is no pre-defined HTML template library like in Python.
4. I'm not sure I can take on this expanded scope. If it was just refactoring in template form, I could have done that. Writing a template engine from scratch is not something I have bandwidth for.

[callendorph]

I think maybe the less ambitious feature would be:

1. Add to Report2Html.tcl at around line 59 some code to copy some user provided content into the <head> section of the HTML file like you were mentioning at the top.
2. Ideally, I think the user would be able to provide an ordered list of files via the project settings that are copied into the output.
   1. User can provide fragments for things like a favicon, CSS styling, etc
   2. Javascript for adding interactivity if any.
   3. Load resources from a CDN
3. I think that worst case, this would allow a user to modify the <body> as well if javascript is enabled in the viewer's browser.

[JimLewis]

Hi Carl,
I think we should start with the less ambitious feature and then pursue the additional features.

I have been on a 3 week business trip. I will be able to test out the code you pushed to your repository when I get back to the office on Monday.

Cheers,
Jim

[JimLewis]

Hi Carl,
The 2023.07 release adds a less ambitious feature. Additional HTML files were added, so the header files were renamed to get a clear association of their purpose. They are now named:

• build_report_header.html - used for the build summary report. Produced by Report2Html
• simulation_header.html - used for the test case report. Produced by Simulate2Html
• requirements_header.html - used in requirements report. Produced by Requirements2Html

The default ones are in the OsvvmLibraries/Scripts directory. You can put replacement ones in your simulation directory. A prefix of the following form can be added to the above files to make them specific to a particular item:
<BuildName>_build_report_header.html
<TestCaseName>_simulation_header.html
<ReportName>_requirements_header.html

In the requirements header, ReportName is either TestSuiteName or BuildName depending on the level of the report.

Best Regards,
Jim

[Paebbels]

I checked the code of livejs. It doesn't support auto reload of local files (file://...).

[JimLewis]

The 2024.0XDev (dev branch) updates this again. The files buil/d_report_header.html, simulation_header.html, and requirements_header.html have been replaced by CssOsvvmStyle.css.

In addition a user may add a file. Currently the name of the file is in Custom-Style.css, however, this is a work in progress.