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

[Bruce Richardson]

On Tue, Jun 06, 2023 at 03:16:27PM +0530, Jerin Jacob wrote:
> On Tue, Jun 6, 2023 at 2:49 PM Bruce Richardson
> <bruce.richardson at intel.com> wrote:
> >
> > On Mon, Jun 05, 2023 at 10:50:48AM +0530, Jerin Jacob wrote:
> > > On Thu, Jun 1, 2023 at 9:08 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>
> > >
> > > > +
> > > > +mandb = find_program('mandb', required: false)
> > > > +if mandb.found() and get_option('enable_docs') and meson.version().version_compare('>=0.55.0')
> > > > +    meson.add_install_script(mandb)
> > >
> > > It does not look like just executing mandb it is adding these man
> > > pages to database
> > >
> > > log:
> > > Running custom install script '/usr/bin/mandb'
> > > Purging old database entries in /home/jerin/.local/man...
> > > Processing manual pages under /home/jerin/.local/man...
> > > Checking for stray cats under /home/jerin/.local/man...
> > > Processing manual pages under /home/jerin/.local/man/cat1...
> > > Purging old database entries in /home/jerin/.local/share/man...
> > > Processing manual pages under /home/jerin/.local/share/man...
> > > Checking for stray cats under /home/jerin/.local/share/man...
> > > Processing manual pages under /home/jerin/.local/share/man/cat1...
> > > 0 man subdirectories contained newer manual pages.
> > > 0 manual pages were added.
> > > 0 stray cats were added.
> > > 0 old database entries were purged.
> > >
> > > [main][dpdk.org] $ man  rte_flow_create
> > > No manual entry for rte_flow_create
> > >
> > > # Following works by providing the path i.e man pages created properly
> > > only db update is missing
> > > man --manpath=/tmp/i/usr/local/share/man/ rte_flow_create
> > >
> > Yes, that is correct.
> >
> > If you install to a non-standard location, then yes you need to update
> > manpath yourself. However, in case you install to a "standard" location,
> > then running mandb will update the database for you. I believe this is the
> > behaviour we should have. I view it as the same as installing binaries in a
> > standard vs non-standard path - if the binaries are placed in a standard
> > location then they are found automatically, but if installed in a custom
> > location, then the user is responsible for ensuring all paths are correct.
> 
> OK. Then I think, we can move "meson.add_install_script(mandb)"
> invocation under !DESTDIR not provided.
> As if DESTDIR is provided then there is no use for mandb.
> 
That would mean adding a new build script to run mandb, since:
* meson doesn't directly support getting environment variables
* DESTDIR may only be set at install time rather than at configuration
  time, so we'll always need to set up the build script

Furthermore, I'd point out that DESTDIR is not going to avoid unnecessary
runs of mandb, since using a special "prefix" setting would also cause the
manpages to not be found.

Overall, I'd view the complexity of avoiding the mandb call not to be
worth it, since calling mandb is largely harmless - bar the time taken to
run it. However, if you feel strongly it should be skipped when installing
with DESTDIR, I'll spin a v2 with the wrapper script added. Let me know
what you think?

/Bruce