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

  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@intel.com>
Reviewed-by: David Marchand <david.marchand@redhat.com>

---

V3: don't use full file paths when generating manpages

V2: add doc update about building or using the manpages
---
 doc/api/doxy-api.conf.in                  |  8 ++--
 doc/api/generate_doxygen.py               |  2 +-
 doc/api/meson.build                       | 54 +++++++++++++++++++----
 doc/guides/contributing/documentation.rst | 12 ++++-
 4 files changed, 63 insertions(+), 13 deletions(-)
  

On Thu, Aug 3, 2023 at 6:44 PM Bruce Richardson
<bruce.richardson@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@intel.com>
> Reviewed-by: David Marchand <david.marchand@redhat.com>
>
> ---
>
> V3: don't use full file paths when generating manpages

Nice!
Thank you Bruce.
  

3/08/2023, Bruce Richardson:
> +#set up common doxygen configuration

A space is missing here

> +man_cdata.set('FULL_PATH_NAMES', 'NO')

Why it has to be disabled? Maybe add a comment?

> +    meson.add_install_script(mandb)

When is it executed exactly?
Will it update the database in case we install in a staging directory,
when preparing a package for later deploying on another machine?

> +.. code-block:: console
> +
> +    export MANPATH=:/path/to/build/doc/api/man

Styling consideration: I think we should indent with 3 spaces
so it is aligned with "code-block".
  

On Tue, Aug 29, 2023 at 11:28:01AM +0200, Thomas Monjalon wrote:
> 3/08/2023, Bruce Richardson:
> > +#set up common doxygen configuration
> 
> A space is missing here
> 
Ack

> > +man_cdata.set('FULL_PATH_NAMES', 'NO')
> 
> Why it has to be disabled? Maybe add a comment?
> 

Sure, will add comment. It's so that the man pages don't include
full paths to the headers, but are just e.g. "rte_eal.h".

> > +    meson.add_install_script(mandb)
> 
> When is it executed exactly?
> Will it update the database in case we install in a staging directory,
> when preparing a package for later deploying on another machine?

Yes, it will. Unfortunately, I can't find any way to just call mandb if we
are installing in a system manpage location on the local machine. Therefore,
I had two options:
1. don't update the manpage database. In this case, the user won't be able to
actually get the newly install manpages
2. always update the local manpage database. In this case, the user
installing the docs will find them, but anyone installing to staging will
experience a slight delay while their local mandb is updated.

I went for #2 on the basis that the delay in the staging case is pretty
harmless, while not actually finding the manpages is more serious.

However, I'm open to other suggestions on how to work this?

> 
> > +.. code-block:: console
> > +
> > +    export MANPATH=:/path/to/build/doc/api/man
> 
> Styling consideration: I think we should indent with 3 spaces
> so it is aligned with "code-block".
> 
Ack.
  

29/08/2023 12:10, Bruce Richardson:
> On Tue, Aug 29, 2023 at 11:28:01AM +0200, Thomas Monjalon wrote:
> > 3/08/2023, Bruce Richardson:
> > > +    meson.add_install_script(mandb)
> > 
> > When is it executed exactly?
> > Will it update the database in case we install in a staging directory,
> > when preparing a package for later deploying on another machine?
> 
> Yes, it will. Unfortunately, I can't find any way to just call mandb if we
> are installing in a system manpage location on the local machine. Therefore,
> I had two options:
> 1. don't update the manpage database. In this case, the user won't be able to
> actually get the newly install manpages

The user can update the manpage database himself.
And if installing from a package, it should have been done automatically.

> 2. always update the local manpage database. In this case, the user
> installing the docs will find them, but anyone installing to staging will
> experience a slight delay while their local mandb is updated.
> 
> I went for #2 on the basis that the delay in the staging case is pretty
> harmless, while not actually finding the manpages is more serious.
> 
> However, I'm open to other suggestions on how to work this?

My concern is polluting the machine of the packager.
What happens when the staging directory is removed?
Is it an error when opening a manpage later?
  

On Wed, Aug 30, 2023 at 11:47:00AM +0200, Thomas Monjalon wrote:
> 29/08/2023 12:10, Bruce Richardson:
> > On Tue, Aug 29, 2023 at 11:28:01AM +0200, Thomas Monjalon wrote:
> > > 3/08/2023, Bruce Richardson:
> > > > +    meson.add_install_script(mandb)
> > > 
> > > When is it executed exactly?  Will it update the database in case we
> > > install in a staging directory, when preparing a package for later
> > > deploying on another machine?
> > 
> > Yes, it will. Unfortunately, I can't find any way to just call mandb if
> > we are installing in a system manpage location on the local machine.
> > Therefore, I had two options: 1. don't update the manpage database. In
> > this case, the user won't be able to actually get the newly install
> > manpages
> 
> The user can update the manpage database himself.  And if installing from
> a package, it should have been done automatically.
> 
> > 2. always update the local manpage database. In this case, the user
> > installing the docs will find them, but anyone installing to staging
> > will experience a slight delay while their local mandb is updated.
> > 
> > I went for #2 on the basis that the delay in the staging case is pretty
> > harmless, while not actually finding the manpages is more serious.
> > 
> > However, I'm open to other suggestions on how to work this?
> 
> My concern is polluting the machine of the packager.  What happens when
> the staging directory is removed?  Is it an error when opening a manpage
> later?
> 
Running mandb doesn't add the manpages from the staging directory to the
database, it simply triggers a scan of the registered manpage directories
on the system, adding new pages found there. It's the man equivalent of
doing an "ldconfig".

/Bruce
  

30/08/2023 12:20, Bruce Richardson:
> On Wed, Aug 30, 2023 at 11:47:00AM +0200, Thomas Monjalon wrote:
> > 29/08/2023 12:10, Bruce Richardson:
> > > On Tue, Aug 29, 2023 at 11:28:01AM +0200, Thomas Monjalon wrote:
> > > > 3/08/2023, Bruce Richardson:
> > > > > +    meson.add_install_script(mandb)
> > > > 
> > > > When is it executed exactly?  Will it update the database in case we
> > > > install in a staging directory, when preparing a package for later
> > > > deploying on another machine?
> > > 
> > > Yes, it will. Unfortunately, I can't find any way to just call mandb if
> > > we are installing in a system manpage location on the local machine.
> > > Therefore, I had two options: 1. don't update the manpage database. In
> > > this case, the user won't be able to actually get the newly install
> > > manpages
> > 
> > The user can update the manpage database himself.  And if installing from
> > a package, it should have been done automatically.
> > 
> > > 2. always update the local manpage database. In this case, the user
> > > installing the docs will find them, but anyone installing to staging
> > > will experience a slight delay while their local mandb is updated.
> > > 
> > > I went for #2 on the basis that the delay in the staging case is pretty
> > > harmless, while not actually finding the manpages is more serious.
> > > 
> > > However, I'm open to other suggestions on how to work this?
> > 
> > My concern is polluting the machine of the packager.  What happens when
> > the staging directory is removed?  Is it an error when opening a manpage
> > later?
> > 
> Running mandb doesn't add the manpages from the staging directory to the
> database, it simply triggers a scan of the registered manpage directories
> on the system, adding new pages found there. It's the man equivalent of
> doing an "ldconfig".

Ah OK
So there is no more concern, thanks.