Doxygen (merge post 64-bit)

[HenningJ]

Since @pjrobertson mentioned doxygen comments somewhere (pull request #815), I decided to finally get serious about that. I pushed the current documentation to the gh-pages branch of the Quicksilver repo. So now it's available from http://quicksilver.github.com/Quicksilver/Reference/. I also added a few things:

• A doxygen config file (see Tools/Doxygen) used to create the documentation. To use it, you have to install Doxygen for MacOS and graphviz (to create nice releationship-graphs). You can than run Doxygen.app, load the config file and build the documentation yourself.
• To make it easier to create the documentation and add it to the XCode help, I added a target to the Quicksilver XCode project called "Build Documentation". Just run it, and when it's finished (it takes quite a while), the documentation is available (and searchable) inside the XCode help. Of course it also needs Doxygen to be installed.
• Added another target called "Upload Documentation". That one builds the documentation as well and then pushes an update to the gh-pages branch. Only works, when you're on the master branch. I'm not sure yet if this is really a good idea, but I like to automate it as much as possible.

[pjrobertson]

A few small things:

• Is there a better GH Pages URL? Maybe something like /Quicksilver/Documentation?
• Can we add some text to the front page of the docs. http://quicksilver.github.com/Quicksilver/Reference/index.html Maybe done in the config file?
• Can we have some comments (similar to what you've written above) somewhere so we know we have to install Doxygen and graphviz etc. for it to work.
• In your upload documentation build phase, will git push origin gh-pages always work? What if someone has their remote called upstream? I don't but I know some people do.
• Is there any way to make the Quicksilver-logo.png just be taken out of the .icns file, so that if we ever change the icon we don't have to update this one as well?
• Doxygen must be installed in /Applications for this to work. Fair enough, but could the be a check incase it's installed in say ~/Applications
• Maybe add a README to the repo page?
• The docs get put in a folder specific to the build type (Debug or Release) is this necessary?
• IT seems like you have to create the docs on the 'Build Documentation' AND 'Upload Documentation' targets. Can the Upload one just upload the docs created by the 'Build Documentation' target?

Other than those few small things, looks good. It's cool to have proper documentation!

[skurfer]

It seems unlikely that this will conflict with pending 64-bit changes, so should we just leave it open?

[HenningJ]

Sorry guys, I've been busy. I agree with Rob, this should cause any trouble, so we could just leave it until after the 64-bit changes.

[pjrobertson]

No worries Henning,

We shouldn't be messing with the .xcodeproj too much when we go 64 bit. Hopefully it won't cause any merge conflicts there.

Status: Fix after 64 bit.

[tiennou]

I'm looking at this and I'm having issues with generating documentation with Doxygen. It's reporting warnings on things in ND externals then errors on a random file. I don't think those @ comments are Doxygen, I'll try appledoc on those to see if that's better.

[tiennou]

Okay, I've got a local branch with appledoc mostly running. Advantages : it does slicker HTML out of the box (Apple docset inspired, 'f course ;-)). IIRC, it misses support for a few things, but on the other hand it can generate docset for Xcode in one pass, which is pretty nice (you get the ⌥-click thing working). I said "Mostly" ? That because it fails with an exception on current master about _contents in "QSCatalogEntry.h", which I fixed by doing #1601.

[tiennou]

As a example, here's the docset I built with it : https://www.dropbox.com/s/l9ov1qzwnwas5ag/com.qsapp.Quicksilver.docset.zip. You can stash that in ~/Library/Developer/Shared/Documentation/DocSets and have fun with it from Xcode documentation viewer.

[HenningJ]

well...go ahead and open your own pull request and close this one. It
hasn't worked correctly for ages anyway. ;-)

On Thu, Sep 19, 2013 at 12:54 AM, Etienne Samson
notifications@github.comwrote:

As a example, here's the docset I built with it :
https://www.dropbox.com/s/l9ov1qzwnwas5ag/com.qsapp.Quicksilver.docset.zip.
You can stash that in ~/Library/Developer/Shared/Documentation/DocSets and
have fun with it from Xcode documentation viewer.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/822#issuecomment-24705988
.

[pjrobertson]

Closing since we have @tiennou's new pull (#1614)