From: ahoward <ah...@po...> - 2004-08-04 19:40:49
|
I whole-heartedly agree with the notion of moving to HTML-only documentation. In practice, this is how I always read documentation from other open source projects (Python, GSL, wxWindow, OpenGL, etc, etc). I also think we should embed documentation in the code, as it is far more likely to get updated this way (having said that, I'm amused be how many drivers in Player proclaim that they where written by me, simply because the author never bothered to change the comment block at the top of the file). I do dislike the visual impact of the additional cruft in the code files, but I'm prepared to overlook this. I looked at a bunch of auto-documentation tools in the past, and found all of them unsatistfactory. Some of the reasons: - Crappy-looking/pooly organized manuals. I was mostly looking at PDF at the time, so this may no longer be a problem. - Insufficient flexibility. These tools are great at generating API lists (i.e., reference manuals), but are less useful for user manuals (which have a very different structure). With these tools, we would probably have to split the existing manual. - Multi-media-poor. Some drivers are quite complex, and benefit enormously from the inclusion of pictures and (imagine!) animations. The resource management for this could be tricky. Having said all of that, I agree with B. that we should not re-invent the wheel. Time to re-visit some of these tools, I guess. A. On Wed, 4 Aug 2004, Brian Gerkey wrote: > hi, > > I've become increasingly dissatisfied with our current system for > maintaining and distributing documentation. I'll explain how it works, > what's wrong with it, and then ask for your help in fixing it. > > Here's how it works now (for Player itself, for the C++ and libplayerc > client libs, and I think for Gazebo): > > (1) Use structured comments to embed documentation in certain header > files that define APIs (e.g., Player interfaces are documented > this way). > > (2) Run a home-brew Python script that parses these headers and produces > LaTeX code. > > (3) Write a bunch of other static LaTeX code to wrap everything and also > to include information not embedded in the headers (e.g., Player > drivers are documented this way). > > (4) Compile all this LaTeX into a .dvi, then a .ps, then a .pdf. > Then also run latex2html to make HTML pages from it. > > We did all this because, being really old-fashioned UNIX geeks, we wanted > to produce and distribute beautiful Postcript manuals. But the Player > User Manual has grown so large that I don't even include it the distro, > because it's a waste of space. > > Our approach has some problems: > > (1) The statically-written code falls out of date very quickly; driver > documentation is often wrong or at least misleading. > > (2) The structured comment parser is brittle (no offense, Andrew; I'm > glad that it works most of the time). > > (3) The resulting documentation looks OK as a PS/PDF but looks > terrible and navigates badly as HTML, and I'm guessing that more > people read the HTML than anything else. > > (4) The whole thing is too slow and static. Nothing gets updated until > I (or Rich or Andrew) build a new manual. And every time I do > that, I have to re-learn how to use the system described above, > then manually upload everything to the website. > > I'm now inclined to think that we have no business developing our own > auto-documentation tools, and that HTML should be the primary (and > possibly only) form for our documentation. > > So I have two questions for all of you smart people: > > (1) What's a better way to do this? > > I want to auto-document as much as possible, with as little > intrusion into the code as possible. And I want the docs to be > "living," in that they should be updated on a more regular basis, > and users should more easily be able to contribute and/or make > corrections. Is there some obvious Doxygen/Wiki setup that we should > be using? > > (2) Do you have expertise with this kind of thing, and are you > interested in heading up (or at least helping in) a transition to > something better? > > We'd all benefit from better docs, but it's not something that I > personally have a lot of time to work on... > > > brian. > > > -- > Brian P. Gerkey ge...@ai... > Stanford AI Lab http://ai.stanford.edu/~gerkey > > > > ------------------------------------------------------- > This SF.Net email is sponsored by OSTG. Have you noticed the changes on > Linux.com, ITManagersJournal and NewsForge in the past few weeks? Now, > one more big change to announce. We are now OSTG- Open Source Technology > Group. Come see the changes on the new OSTG site. www.ostg.com > _______________________________________________ > Playerstage-developers mailing list > Pla...@li... > https://lists.sourceforge.net/lists/listinfo/playerstage-developers > Andrew Howard email: ah...@po... Department of Computer Science http: www-robotics.usc.edu/~ahoward University of Southern California phone: 1 (213) 740 6416 Los Angeles, CA, U.S.A. 90089-0781 fax: 1 (213) 821 5696 << Insert pithy saying here >>> |
From: Kratochvil, B. E. <kra...@ir...> - 2004-08-05 16:22:02
|
Hello, I'm by no means an expert on this, but I am a fan of Doxygen. I think with a little thought (and some time) it can answer most of the questions you posed. - Crappy-looking/poorly organized manuals. I was mostly looking at PDF at the time, so this may no longer be a problem. I believe this is more of a developer issue than a documentation tool problem. Some of these tools take a while to get setup and your final document organized, which many of us don't want to spend the time to do. Doxygen allow you to use html in the documentation, so you really don't have many restrictions on what you put in for documentation and how it looks. I also think they use style sheets reasonably well, so you have a lot of flexibility. Player already has a pretty good organization for the manuals, so it should really just take some work as to how to translate that to the next program. - Insufficient flexibility. These tools are great at generating API lists (i.e., reference manuals), but are less useful for user manuals (which have a very different structure). With these tools, we would probably have to split the existing manual. I agree on this one. Most tools are great for making API references, but are a bit lacking when it comes to making a user manual. On the flip side, I recently ran into a project that seems to do good job of documenting the API and making a reference manual all with Doxygen. Check out the reference manual at http://cimg.sourceforge.net/reference/index.html. It's not a huge manual, but you can see how something similar for Player could be built. - Multi-media-poor. Some drivers are quite complex, and benefit enormously from the inclusion of pictures and (imagine!) animations. The resource management for this could be tricky. The way the last project I mentioned handled the images and other multimedia content was just to dump them all in the subdirectory where the documentation was built and use relative URIs in your html. It would be a little more complicated in terms of Player, but I think it could be done cleanly. One thing that may be tricky with Player is keeping all the different types of documentation partitioned. It would be good to have a way to keep the client libs, server, examples, and whatever else all separated as they currently are. I have no idea as to how you'd do this one in Doxygen, but I don't think it should be that bad. Well, that's my $.02. I'd be willing to help on this effort in a few months. I'm under the gun right now, but life will get better in November (I hope). Cheers, bk |