doxygen (was: Re: [Nut-upsdev] NUT and Automake)

[Charles Lepple]

On 10/15/06, Peter Selinger <selinger at mathstat.dal.ca> wrote:
> Perhaps it should go in the man/ directory, and be called something
> like tripplite_usb.doxy? This is assuming that there would be one such
> file for each driver/man page. If there is only a single file for
> all supported man pages, then the name Doxyfile would be useable.

Doxygen can create man pages for functions, but I don't think you
could reconfigure it to generate output like our existing driver and
daemon man pages.

I was using it for cross-referencing the source code. I agree with the
notion that if it relates to one driver, then that driver name should
be in the config file name.

On the other hand, what I was thinking is that you could pass
"--enable-doxygen=newhidups" or "--enable-doxygen=upsc" to configure,
and then doxygen would read the source files appropriate to each of
those programs (i.e. turn Doxyfile into a template, and have the
--enable-doxygen parameter replace tripplite_usb).

> > Eventually, I would like to put some more documentation into the core
> > NUT files, since there are a number of assumptions that aren't obvious
> > if you are just reading driver code.
> >
> > The man page for tripplite_usb is actually generated with the Perl
> > POD-to-man translator, but I didn't want to put another dependency
> > into the old build system - so I just rebuilt the man page by hand.
> > This is another candidate for automation.
>
> Yes, assuming that all maintainers who might want to build this file
> have pod2man available. It's easy to cause "make dist" to distribute
> both the doxy file and the resulting man page, so that tarball-users
> will not have to rebuild it.

Right (except for the doxyfile part; see above). I'll have to check
how autoconfiscated packages that have lex or yacc parsers handle
that, because there should be a way to say "if the man page isn't out
of date, don't look for pod2man".

> By the way, with the new "make distcheck" mechanism, it should be
> relatively easy to automatically generate a "daily tarball", or
> perhaps to trigger such a tarball to be build after each commit.  Do
> you know how to hook into SVN to trigger such a post-commit action?
> (Moreover, if "make distcheck" fails, then a bug has been immediately
> discovered).

Should be possible, but I would be a little scared of trying the
post-commit hook on svn.debian.org. That machine seems to get bogged
down a lot.

If someone commits two revisions in a row, do you want to kill the
first build, or leave it running to see if that version broke
something? We probably want to serialize builds, so as not to have a
ton of temporary copies of NUT lying around.

Also, to check everything, we should probably do a fresh checkout each
time, or at least run autoreconf. Otherwise, we will miss errors in
auto*-related checkins.

Daily tarballs should be a lot easier than per-commit.

-- 
- Charles Lepple