Unable to sleep tonight because of an issue that arose this evening that I just couldn't stop thinking about...

I was working on the Developer's page on the wiki and was putting in links for the various technologies in use. One of those being D-BUS. All fine and dandy, except that the D-BUS page had little if any useful information on the D-BUS services or clients on the laptop.

Fine, there's a link that says "read the source"... but that's not really acceptable. How do I even know where in the source to look when I don't know what's being made available on D-BUS (I've tried to address that somewhat by describing the various services I know exist)? I wind up having to grep through looking for dbus (there's a heck of a lot of dbus stuff in there (key seems to be to look for dbus.service)). I don't even see NetworkManager in there, though I know it must be somewhere deep within the system providing it's D-BUS api.

Which brings me to the need that kept me from sleeping. We need a documentation system running automatically every night and producing reference docs for the whole project. What we'd want is something that can handle general code structures, but can be extended to handle things such as D-BUS API annotations in somewhat intelligent manners (e.g. creating a D-BUS Service Index alongside the main documentation, or even just making the D-BUS API stuff integrate nicely into the regular docs).

We'd want to be able to handle documentation formatting, including separate documentation (so that we don't have to put all of our reference docs right in the run-time code). We'll also want to be able to include links to source-code usage samples for functions where ever possible (preferably auto-generated).

We could try epydoc, but I'd really have to dig into it to figure out how to make these kind of customizations, and I'm not sure it's source-code-model is sufficient to handle the kind of things we'd want to do. Still, at least it's working today and ready-to-go, so we might get basic documentation up and updating regularly and worry about refinements as we use the results.