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

[Bruce Richardson <bruce.richardson@intel.com>]

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. If the
  manpages are not installed in system location i.e. one not in MANPATH,
  then this update will have no effect, as only system locations are
  scanned.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Reviewed-by: David Marchand <david.marchand@redhat.com>

---

V4: fix whitespace issues.
    add clarifying notes about mandb updating the database by
    scanning system locations only.

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                       | 58 +++++++++++++++++++----
 doc/guides/contributing/documentation.rst | 12 ++++-
 4 files changed, 67 insertions(+), 13 deletions(-)

diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in
index a88accd907..1ba72e6221 100644
--- a/doc/api/doxy-api.conf.in
+++ b/doc/api/doxy-api.conf.in
@@ -123,11 +123,13 @@ EXAMPLE_PATTERNS        = *.c
 EXAMPLE_RECURSIVE       = YES
 
 OUTPUT_DIRECTORY        = @OUTPUT@
+FULL_PATH_NAMES         = @FULL_PATH_NAMES@
 STRIP_FROM_PATH         = @STRIP_FROM_PATH@
-GENERATE_HTML           = YES
-HTML_OUTPUT             = @HTML_OUTPUT@
+GENERATE_HTML           = @GENERATE_HTML@
+HTML_OUTPUT             = html
 GENERATE_LATEX          = NO
-GENERATE_MAN            = NO
+GENERATE_MAN            = @GENERATE_MAN@
+MAN_LINKS               = YES
 
 HAVE_DOT                = NO
 
diff --git a/doc/api/generate_doxygen.py b/doc/api/generate_doxygen.py
index d3a22869f6..c704f13018 100755
--- a/doc/api/generate_doxygen.py
+++ b/doc/api/generate_doxygen.py
@@ -7,7 +7,7 @@
 
 pattern = re.compile('^Preprocessing (.*)...$')
 out_dir, *doxygen_command = sys.argv[1:]
-out_file = os.path.join(os.path.dirname(out_dir), 'doxygen.out')
+out_file = os.path.join(out_dir + '.out')
 dep_file = f'{out_dir}.d'
 with open(out_file, 'w') as out:
     subprocess.run(doxygen_command, check=True, stdout=out)
diff --git a/doc/api/meson.build b/doc/api/meson.build
index 2876a78a7e..8b0ced423b 100644
--- a/doc/api/meson.build
+++ b/doc/api/meson.build
@@ -29,11 +29,11 @@ example = custom_target('examples.dox',
         install_dir: htmldir,
         build_by_default: get_option('enable_docs'))
 
+# set up common doxygen configuration
 cdata = configuration_data()
 cdata.set('VERSION', meson.project_version())
 cdata.set('API_EXAMPLES', join_paths(dpdk_build_root, 'doc', 'api', 'examples.dox'))
 cdata.set('OUTPUT', join_paths(dpdk_build_root, 'doc', 'api'))
-cdata.set('HTML_OUTPUT', 'html')
 cdata.set('TOPDIR', dpdk_source_root)
 cdata.set('STRIP_FROM_PATH', ' '.join([dpdk_source_root, join_paths(dpdk_build_root, 'doc', 'api')]))
 cdata.set('WARN_AS_ERROR', 'NO')
@@ -41,14 +41,35 @@ if get_option('werror')
     cdata.set('WARN_AS_ERROR', 'YES')
 endif
 
-doxy_conf = configure_file(input: 'doxy-api.conf.in',
-        output: 'doxy-api.conf',
-        configuration: cdata)
+# configure HTML doxygen run
+html_cdata = configuration_data()
+html_cdata.merge_from(cdata)
+html_cdata.set('GENERATE_HTML', 'YES')
+html_cdata.set('GENERATE_MAN', 'NO')
+html_cdata.set('FULL_PATH_NAMES', 'YES')
 
-doxy_build = custom_target('doxygen',
+doxy_html_conf = configure_file(input: 'doxy-api.conf.in',
+        output: 'doxy-api-html.conf',
+        configuration: html_cdata)
+
+# configure manpage doxygen run
+man_cdata = configuration_data()
+man_cdata.merge_from(cdata)
+man_cdata.set('GENERATE_HTML', 'NO')
+man_cdata.set('GENERATE_MAN', 'YES')
+# for manpages, have the pages only titled with the header name,
+# rather than the full path to the header
+man_cdata.set('FULL_PATH_NAMES', 'NO')
+
+doxy_man_conf = configure_file(input: 'doxy-api.conf.in',
+        output: 'doxy-api-man.conf',
+        configuration: man_cdata)
+
+# do doxygen runs
+doxy_html_build = custom_target('doxygen-html',
         depends: example,
         depend_files: 'doxy-api-index.md',
-        input: doxy_conf,
+        input: doxy_html_conf,
         output: 'html',
         depfile: 'html.d',
         command: [generate_doxygen, '@OUTPUT@', doxygen, '@INPUT@'],
@@ -56,5 +77,26 @@ doxy_build = custom_target('doxygen',
         install_dir: htmldir,
         build_by_default: get_option('enable_docs'))
 
-doc_targets += doxy_build
-doc_target_names += 'Doxygen_API'
+doc_targets += doxy_html_build
+doc_target_names += 'Doxygen_API(HTML)'
+
+doxy_man_build = custom_target('doxygen-man',
+        depends: example,
+        depend_files: 'doxy-api-index.md',
+        input: doxy_man_conf,
+        output: 'man',
+        depfile: 'man.d',
+        command: [generate_doxygen, '@OUTPUT@', doxygen, '@INPUT@'],
+        install: get_option('enable_docs'),
+        install_dir: get_option('datadir'),
+        build_by_default: get_option('enable_docs'))
+
+doc_targets += doxy_man_build
+doc_target_names += 'Doxygen_API(Manpage)'
+
+# refresh the manpage database on install
+# if DPDK manpages are installed to a staging directory, not in MANPATH, this has no effect
+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)
+endif
diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst
index 79616e5610..4eb62fc36a 100644
--- a/doc/guides/contributing/documentation.rst
+++ b/doc/guides/contributing/documentation.rst
@@ -182,7 +182,17 @@ To build the documentation::
 
 See :doc:`../linux_gsg/build_dpdk` for more detail on compiling DPDK with meson.
 
-The output is generated in the directories ``build/doc/html/{api,guides}``.
+The output is generated in the directory ``build/doc/``, with:
+
+* HTML versions of the guide docs, e.g. Getting Started Guides, Programmers Guide, in ``build/doc/guides/html``
+* HTML version of the API documentation in ``build/doc/api/html``
+* Man-page version of the API documentation in ``build/doc/api/man``.
+  If not installing DPDK system-wise, these pages can be accessed by adding this directory to the ``MANPATH`` environment variable.
+  For example:
+
+.. code-block:: console
+
+   export MANPATH=:/path/to/build/doc/api/man
 
 .. Note::
 
-- 
2.39.2