Re: Using RoboDoc for tapset documentation

[Mike Mason <mmlnx at us dot ibm dot com>]

Eugene Teo wrote:
> Mike Mason wrote:
> > I've been experimenting with something called RoboDoc to generate
> > documentation from tapset file comments.  You can see an example that
> > uses the sockets tapset at http://www.mwmnet.com/systemtap/robodoc/. 
> > The socket.stp file shows the robodoc markup I used in the tapset file. 
> > The other directories show the resulting output in various formats. 
> > It's not perfect, but it's pretty good, IMHO.  Still needs fine tuning
> > in some areas.
> >
> > Please take a look and let me know what you think.  Sure would be nice
> > to standardize tapset documentation using something like this.
>
> Very nice. Are there alternatives or is this the best one you tried?

There are others, but RoboDoc was the only doc generator I found that creates so many different output formats and doesn't require support for the language being documented.  The documentation can be generated strictly from comments.  It also doesn't require special tags that can make the comments hard to read.  

Natural Docs is a possible alternative, but it only produces html.  If that's all we need then it should be considered, too. 

That being said, if anyone knows of a better tool, let me know.

> > Question... RoboDoc is GPL'd, but doesn't appear to be shipped in any
> > distros.  Is that an issue?  Could we just include RoboDoc in the
> > SystemTap src tree?
>
> Would be silly if we just include RoboDoc into the src tree. Probably better
> if RoboDoc is packaged separately if we decided to use it.

Yeah, you're right.  What I meant was we'd need to make it available somehow since it would be a requirement for the doc part of the build.  How we accomplish that is TBD.

Mike

> Eugene