What are the characteristics for a good report generation software for reporting and tracking software benchmarking results

In my view there are two things important in software documentation/report:

• Technical documentation, for each function/class you describe the input and output, and what it does. This could also include the class hierarchy if you are using object orientation.
• User documentation: This includes stuff like:
  • What is the goal of the library, what are the requirements
  • How and why have you designed the library in a particular way. Which design patterns have you used (in case of OOP), or why have you ordered your procedures in a certain way. For your professor this is also important if he wants to see if you can think on a high abstraction level, and not only in the nitty gritty details.
  • Example uses (tutorials) which show a few good examples of how the library can be used. You can link back to design decisions and point out that this example shows why it was a good idea to design in a particular way.

In a web-serving context, putting the stylesheet in a separate file is MUCH preferred. It will lead to much better in-browser and in-Web-middleware caching behavior, so have much better performance (and impose lower load on all of the systems involved). There are other benefits as well (e.g. better modularity, versioning, ...).

But that's not your case. You seem to have a situation where having a single, all-inclusive, self-contained HTML files would be preferable. The parts of the document (like CSS) that can be separated...well, if someone's not careful in transmitting the files, they will be separated. And then the document won't "look right." It will look broken. Perhaps very broken, depending on how much you rely on CSS. So by all means, embed your styles.

Aside About Images and Email

In HTML, images are often left external. For truly self-contained files, you'd like them to be included too. That is now generally possible if you base64 encode them. There is a older alternative strategy, MHTML, for sending images and other content through email. Directly stating base64 data seems to be better supported these days, especially for browser viewing.

But if you are encoding HTML (reports, documents, etc.) for email (i.e. as the primary email message, rather than as attachments), beware. This is a bit of a dark art, even today requiring a lot of expertise about the vagaries of the different end-points/mail programs. Outlook vs. Gmail vs. XYZ--they can be very different, not only from each other, but also from the HTML you would use and expect to work correctly across their browser products. Email HTML is a tricky devil, and it doesn't play by the normal rules. Stylesheets there, for example, are not recommended at all, because they will often be intentionally disregarded. If you want to style those, write your stylesheet for composing your HTML email, then use a library to deconstruct your stylesheet and explicitly pack the appropriate styling into style attributes. See premailer for an example of a library that helps you style email HTML in a way that will be respected by the average mail program.