Here's another option to consider... For osgEarth we use ReadTheDocs. You store your documentation right in the source repo alongside the code. That's nice - it keeps everything in one place and lets you revision the documentation as you would anything else. Docs are in RST format, making them human-readable as plain text as well.
RTD integrates automatically with revision control systems. If I push a change, the doc site updates automatically within minutes. (That's github, not sure about other systems.) You can see our RTD-hosted docs site here: http://docs.osgearth.org ReadTheDocs is at https://readthedocs.org/ Enjoy -gw Glenn Waldron / @glennwaldron On Sun, Aug 31, 2014 at 10:11 AM, Bram Vaessen <bram.vaes...@gmail.com> wrote: > Hi Björn, > > My idea is actually closely related with your point 2: the in depth > documentation of OSG. As far as I know however, doxygen is generated from > the comments in the source code, so everyone who wants to add or say > something about any function would have to do it in the source code (please > correct me if I'm wrong), which doesn't seem ideal to me. > > Also the doxygen seems to list absolutely everything and makes no > distinction between functions/classes that are meant to be used by the user > of OSG, and classes and functions that are more private and used inside > OSG, and I think this is detrimental to understanding OSG from it. > > In my ideal view of the OSG documentation (besides good examples and > tutorials), it would include an API documentation where it's clear what > classes and functions are part of the interface of OSG and how you can use > them. > > The level of details would be something like this (just an example): > > http://wiki.secondlife.com/wiki/LlSensor > > So instead of one or two lines per function, it could include explanations > of when and how to use the function, examples of usage, details on the > exact nature and limits of the arguments and return values of the function, > caveats and discussion points. etc. > > Again correct me if I'm wrong, but I don't think this is possible in > doxygen? > > I believe/hope that if the groundwork and basic structure for this is > created and perhaps partially filled by a limited number of people, then > this type of documentation can then further be generated and maintained by > the community. > > ------------------ > Read this topic online here: > http://forum.openscenegraph.org/viewtopic.php?p=60876#60876 > > > > > > _______________________________________________ > osg-users mailing list > osg-users@lists.openscenegraph.org > http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org >
_______________________________________________ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
