[Docs] Generate online and offline documentation from the XML reference (outside of intellisense)
Posted Thursday, 8 October, 2009 - 17:24 by the Fiddler| Project: | The Open Toolkit library |
| Version: | 1.0-beta-3 |
| Component: | Documentation |
| Category: | task |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | closed |
Jump to:
Description
The XML reference includes OpenTK.xml, OpenTK.Compatibility.xml and OpenTK.GLControl.xml.
We need a way to produce HTML reference pages suitable for viewing online. It would also be nice if we could produce PDF (or another format) suitable for offline use, but this is a secondary concern.
A quick search shows three suitable applications:
- NDoc, which used to be the de facto standard for documentation, but seems to be dead since 2005.
- SandCastle, sponsored by Microsoft. I believe this is windows-only, which makes it unsuitable for our purposes.
- MonoDoc, which is sponsored by the Mono project. This actually uses it's own documentation format, but can import XML files produced by the C# compiler.
All things considered, MonoDoc seems as the best solution - provided it can be used standalone, without installing the whole Mono runtime.
Have you ever used any of these applications to produce documentation? Any recommendations? Are you aware of any alternatives?
Comments
#1
I have tested monodoc and it works nicely. However, the generated documentation has a number of issues, like missing descriptions. Maybe I have overlooekd some commandline option - the idea is to populate the various class 'desrciptions' using the summary element.
#2
Hi.
> Have you ever used any of these applications to produce documentation?
No.
> alternatives?
Perhaps
Natural Doc
http://www.naturaldocs.org/
or
Doxygen
http://www.stack.nl/~dimitri/doxygen/index.html
I make some works with it and its good enough for me.
And for you? :-)
Cu, Horst.
P.S.: Great work
#3
I have integrated doxygen into the build script and it works great. Still tweaking the output options, build process and error messages, but it already produces usable html and pdf documentation.
#4
Closing issues resolved in 1.0-beta-3.