[PATCH v2] doc: build manpages as well as html output

[Bruce Richardson]

On Tue, Jul 04, 2023 at 10:21:22AM +0200, David Marchand wrote:
> On Tue, Jun 6, 2023 at 3:13 PM Bruce Richardson
> <bruce.richardson at intel.com> wrote:
> >
> > Doxygen can produce manpage output as well as html output for the DPDK
> > APIs. However, we need to do this as a separate task as the manpage
> > output needs to be placed in a different location post-install to the
> > html output (/usr/local/share/man vs /usr/local/share/doc/).
> >
> > Changes required are:
> > * Add configurable options for manpage output and html output to the
> >   doxygen config template. (Remove option for html output path as it's
> >   always "html")
> > * Modify API meson.build file to configure two separate doxygen config
> >   files, for HTML and manpages respectively.
> > * Change doxygen wrapper script to have separate output log files for
> >   the manpage and HTML jobs, to avoid conflicts
> > * Add "custom_targets" to meson.build file to build the HTML pages and
> >   the manpages, with individual install locations for each.
> > * Where supported by meson version, call "mandb" post-install to update
> >   the man database to ensure the new manpages can be found.
> >
> > Signed-off-by: Bruce Richardson <bruce.richardson at intel.com>
> 
> Nice.. we should have done this sooner :-).
> 
> Reviewed-by: David Marchand <david.marchand at redhat.com>
> 
> 
> There may be some polishing to do later.
> Looking at the result for rte_eal_init, I see that the generated
> manual starts with a reference to the rte_eal.h header with a path
> relative to its location in the DPDK tree.
> $ MANPATH=build-gcc/install/share/man man rte_eal_init | head -5
> lib/eal/include/rte_eal.h(3)
>                                            DPDK
> 
> lib/eal/include/rte_eal.h(3)
> 
> NAME
>        lib/eal/include/rte_eal.h
> 
> At least, it is possible to ask for this header man with "man
> rte_eal.h", but it is a bit confusing.
> Is there something we can do on this side?
> 

Not sure, not really familiar with how doxygen works generating manpages
and the options supported, etc. etc. Mainly I just looked at the
build-system side to support this, since I really missed having manpages
for DPDK functions to quickly check parameter order.

/Bruce