[v4] doc: build manpages as well as html output
Checks
Commit Message
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(-)
Comments
31/08/2023 11:49, Bruce Richardson:
> 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>
Acked-by: Thomas Monjalon <thomas@monjalon.net>
> From: Thomas Monjalon [mailto:thomas@monjalon.net]
> Sent: Thursday, 31 August 2023 12.12
>
> 31/08/2023 11:49, Bruce Richardson:
> > 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>
>
> Acked-by: Thomas Monjalon <thomas@monjalon.net>
>
Having followed the discussion where the "cross build" details were clarified...
Acked-by: Morten Brørup <mb@smartsharesystems.com>
31/08/2023 17:48, Morten Brørup:
> > From: Thomas Monjalon [mailto:thomas@monjalon.net]
> > Sent: Thursday, 31 August 2023 12.12
> >
> > 31/08/2023 11:49, Bruce Richardson:
> > > 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>
> >
> > Acked-by: Thomas Monjalon <thomas@monjalon.net>
> >
>
> Having followed the discussion where the "cross build" details were clarified...
>
> Acked-by: Morten Brørup <mb@smartsharesystems.com>
Applied, thanks.
@@ -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
@@ -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)
@@ -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
@@ -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::