[PATCH v2] doc: build manpages as well as html output
Bruce Richardson
bruce.richardson at intel.com
Tue Jun 6 15:12:30 CEST 2023
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>
---
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
More information about the dev
mailing list