Sorry -- it took longer than I intended to get back to you.
In the near term, you can work around the usage formatting issue by not using newlines in the usage message. We're going to handle that in an update coming soon, but if you make the entire usage message on one line (simply put a space between the end of the first and start of the second template), it should do the right thing.
Re: your other questions, we've recently gotten other feedback about exposing the DocumentationTools functions for programmatic use; I'm considering it. Making them top-level functions comes with an implicit understanding that they're integrated with the language more widely among other things, and we weren't developing with that specifically in mind, so this might be a gradual process.
The documentation build code that is shipping with the desktop products is capable of building HTML pages already, believe it or not. The relevant function is PacletDocumentationBuild (https://reference.wolfram.com/language/PacletTools/ref/PacletDocumentationBuild.html), where you use:
Needs["PacletTools`"];PacletDocumentationBuild[paclet, outdir, "HTML"]
Hope this helps -- let us know if you have other issues!
