Allegro.cc - Online Community
Post Reply

Allegro.cc Forums » Programming Questions » Favorite flavor of docs?

Credits go to Peter Hull for helping out!
rss feed Print
Favorite flavor of docs?
Edgar Reynaldo
Member #8,592
May 2007
avatar

I recently finished my basic cmake build system for my library, Eagle.

Now I need to document the library, and I'm seeking advice on the best format and tools to use to make some nice docs.

Some options I'm considering :

1) Sphinx and rST (Python and reStructuredText)

2) Doxygen autogenerated docs

Things to keep in mind are this is a C++ library, and the docs are virtually non-existent so I can start from scratch and not worry about porting anything.

Both 1 and 2 can make CHM docs, which is my target besides html. I don't care about man or pdf unless somebody else wants them in that format.

2) has the advantage of interfacing nicely with C++ and being able to auto generate most of the documentation

1) needs separate doc files, which can be a problem sometimes keeping in sync with the source code

So, ideas, suggestions?

Cookies on standby.

EDIT
Here's a prototype of a doxygen produced CHM file for my library - take a look and tell me if you like it :

Eagle.chm

Peter Hull
Member #1,136
March 2001

I like Doxygen because it's simple and also similar to javadoc which I also use.

Edgar Reynaldo
Member #8,592
May 2007
avatar

Doxygen is amazing so far and is so easy and so quick, I think it's the winner here. It can include .md files as well, which is awesome. And then turn it all into CHM, HTML, Man, Latex, XML, and PDF with another tool.

I'd love to support sphinx but I don't want to learn yet another style of markdown in reStructuredText.

And the javadoc documentation style is simple and neat.

Well, I know what I'll be doing for the next month. Writing docs. :-X

8-)

Credits go to Peter Hull! Cuz he's the only one cool enough to reply. >:(

EDIT
Forgot your cookie! Here!

{"name":"perfect-paleo-double-chocolate-cookies-1.jpg","src":"\/\/djungxnpq2nug.cloudfront.net\/image\/cache\/0\/4\/04c2a7ce981b62f10580cee37a48113f.jpg","w":700,"h":1050,"tn":"\/\/djungxnpq2nug.cloudfront.net\/image\/cache\/0\/4\/04c2a7ce981b62f10580cee37a48113f"}perfect-paleo-double-chocolate-cookies-1.jpg

Peter Hull
Member #1,136
March 2001

Credits go to Peter Hull! Cuz he's the only one cool enough

Yeah I get this a lot ;)

Thanks for the e-cookie, a real one wouldn't have been good for my waistline...

Edgar Reynaldo
Member #8,592
May 2007
avatar

Too true. ;D

If any of you were going to use Eagle, what would you like to see in the docs?

A widget creation tutorial? Common use tutorial?

Eagle is a GUI library, but it has many many more features than just being a GUI.

Post Reply
Go to: