Documentation overhaul

[kernfel]

The PDF is not a particularly user-friendly document, nor is it efficient to maintain. Ideally, documentation should be available right inside the software, a saccade or click away from the component it relates to. It should also be available online, e.g. in the wiki here, for reference during paper writing and the like.
Both in-software and online versions should probably be compiled from the same source material, which should in turn be updated in lockstep with changes to the code... I hope that's not too much to ask of my future self and whatever tool I'll find to do this.

[tnowotny]

Great to see your commitment to continue improving the software. Let me know if I can help.

[kernfel]

Will do. In fact... I should probably look this up myself, but, do you know if Doxygen can compile into a format that would be adequate for help that's integrated into the GUI?

Mostly, I needed a way to stop myself from marching on into weeks of work on these improvements after doing the stuff that Naoki needed more urgently - I'm being paid for other things, supposedly. I'm hearing good things from Naoki though, the optical stuff is progressing nicely... and if that works out, I feel we should have a more presentable release out by the time his work bears fruit.

[tnowotny]

Doxygen came to my mind but I am not sure it's appropriate. I have compiled it into html or (latex based) pdf so far but it's pretty much geared towards documenting code packages not gui driven applications.
I suspect QT only has manual popup help entries you would enter through QT creator? That would be fairly unusable? Or use that to display links to html based help pages? I feel there should be better solutions to this.

[kernfel]

Qt can actually display HTML (and markdown, as of 5.14), or even embedded web content... though I'd rather not require internet access, if I can help it. There's also the possibility of adding rich text help popups on individual widgets, which might be useful to more thoroughly document the parameter dialogs.

A related point, I think, is that

a saccade or click away from the component it relates to

should probably also apply on the development side -- the greater the distance between code and documentation source, the likelier it is that changes go unreported. So adding Doxygen style comments directly where e.g. parameters are defined and compiling them into their relevant (possibly composite) documentation files would go a long way towards ensuring consistency.