[PATCH v2] 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.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>

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

diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in
index 967aa11701..6e5be9b469 100644
--- a/doc/api/doxy-api.conf.in
+++ b/doc/api/doxy-api.conf.in
@@ -125,10 +125,11 @@ EXAMPLE_RECURSIVE       = YES
 
 OUTPUT_DIRECTORY        = @OUTPUT@
 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..104b91517b 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,31 @@ 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')
 
-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')
+
+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 +73,24 @@ 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)'
+
+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 7fcbb7fc43..e0b672ffbb 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