Debian-Docbase allows to register some HTML documentation;
My old package definition added placeholder config, which renders
the documentation configuration invalid (as pointed out by Lintian).
However, I still think it is a good idea to have the anchor point
already defined, and thus I came up with the idea of in fact
providing some usable placeholder content...
As it turns out, we also have a placeholder page at the Lumiera website,
where the User Manual is assumed to be located later — so why not extend
this one and then provide the HTML-rendering for the DEB package?
To allow for this setup
* I have now extended the placeholder page for the Website
to include some generic description about Lumiera (from the 'about' page)
* Furthermore, I added the screenshot (from the »Outer Space« page)
* and I use this a an opportunity to document the various test / demo
facilities currently available in the GUI, since these are rather obscure.
While only intended for the developer, it seems still worthwhile
to describe the possible effects — it may well be that we retain
some of that test/demo functionality and in that case, we have
now already some starting point for a documentation
* Then, to include that page as stand-alone HTML, I used the 'Print Edit WE'-plugin
from Firefox, to encode the images as inline-base64 URLs (which are restored
by a tiny JavaScript embedded into that page)
* and last but not least, our SCons buildsystem needs the ability
to install such a documentation file, since it seems most adequate
to handle this requirement as part of the generic installation (and
not hidden in some Debian scripting)
- remove obsolete configuration settings
- walk through all settings according to the documentation
https://www.doxygen.nl/manual/config.html
- now try to use the new feature to rely on Clang for C++ parsing
- walk through the doxygen-warnings.txt and fix some obvious misspellings
and structural problems in the documentation comments.
With Debian-Trixie, we are now using Doxygen 1.9.8 —
which produces massively better results in various fine points.
However, there are still problems with automatic cross links,
especially from implementation to the corresponding test classes.
BuilderDoxygen and BuilderGCH are external plug-ins,
not developed in this project and probably unmaintained.
TODO: decide how to fix or replace them...
- upgrade the configuration to a current version
- provide a frontpage with cross-links to other documentation
- define a set of modules; relevant classes and files can be
added to these, to create a exploration path for new readers
- fix a lot of errors in documentation comments
- use a custom configuration for the documentation pages
- tweak the navigation, the sections and further arrangements
