A client is using Google Sites for API documentation. Initially, this documentation was generated by a python script that reads the java source code (tld, tag library descriptor, files in this case) and uses the Google Sites API to create/update pages at the site.
This worked great - until non-engineers wanted to update descriptions, examples and add "see also"s. They naturally wanted to go direct to the Google Site and update the text there. However this wasn't reflected in the checked in tlds and thus gets overwritten on updates.
So now we propose that the Google Site will be the definitive source for the text part of the documentation, while the structure will continue to be derived from the TLD. A utility will do validation between the TLD and the site. This inevitably leads to:
How do we insert meta information into the Google Site HTML, given the (reasonable) propensity for google to strip all non-relevant/potential harmful info? I.e. we'd like to do something like:
<div class="function-description">
This function is really useful and you should use it.
</div>
Unfortunately, class is one of the attributes that is stripped - plus this could be overridden by sites for its own formatting (e.g. <div class="sites-codeblock sites-codesnippet-block">).
We have found that this seems to work:
<div rel="fn-description">
This function is really useful and you should use it.
</div>
but we wonder if it might have pitfalls and/or if others have faced a similar need and found a more elegant way to overcome it.
Thanks for reading this far!