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.
Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
doc/api/doxy-api.conf.in | 7 ++---
doc/api/generate_doxygen.py | 2 +-
doc/api/meson.build | 52 +++++++++++++++++++++++++++++++------
3 files changed, 49 insertions(+), 12 deletions(-)
Comments
On Thu, Jun 1, 2023 at 9:08 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>
> +
> +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)
It does not look like just executing mandb it is adding these man
pages to database
log:
Running custom install script '/usr/bin/mandb'
Purging old database entries in /home/jerin/.local/man...
Processing manual pages under /home/jerin/.local/man...
Checking for stray cats under /home/jerin/.local/man...
Processing manual pages under /home/jerin/.local/man/cat1...
Purging old database entries in /home/jerin/.local/share/man...
Processing manual pages under /home/jerin/.local/share/man...
Checking for stray cats under /home/jerin/.local/share/man...
Processing manual pages under /home/jerin/.local/share/man/cat1...
0 man subdirectories contained newer manual pages.
0 manual pages were added.
0 stray cats were added.
0 old database entries were purged.
[main][dpdk.org] $ man rte_flow_create
No manual entry for rte_flow_create
# Following works by providing the path i.e man pages created properly
only db update is missing
man --manpath=/tmp/i/usr/local/share/man/ rte_flow_create
> +endif
> --
> 2.39.2
>
On Mon, Jun 05, 2023 at 10:50:48AM +0530, Jerin Jacob wrote:
> On Thu, Jun 1, 2023 at 9:08 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>
>
> > +
> > +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)
>
> It does not look like just executing mandb it is adding these man
> pages to database
>
> log:
> Running custom install script '/usr/bin/mandb'
> Purging old database entries in /home/jerin/.local/man...
> Processing manual pages under /home/jerin/.local/man...
> Checking for stray cats under /home/jerin/.local/man...
> Processing manual pages under /home/jerin/.local/man/cat1...
> Purging old database entries in /home/jerin/.local/share/man...
> Processing manual pages under /home/jerin/.local/share/man...
> Checking for stray cats under /home/jerin/.local/share/man...
> Processing manual pages under /home/jerin/.local/share/man/cat1...
> 0 man subdirectories contained newer manual pages.
> 0 manual pages were added.
> 0 stray cats were added.
> 0 old database entries were purged.
>
> [main][dpdk.org] $ man rte_flow_create
> No manual entry for rte_flow_create
>
> # Following works by providing the path i.e man pages created properly
> only db update is missing
> man --manpath=/tmp/i/usr/local/share/man/ rte_flow_create
>
Yes, that is correct.
If you install to a non-standard location, then yes you need to update
manpath yourself. However, in case you install to a "standard" location,
then running mandb will update the database for you. I believe this is the
behaviour we should have. I view it as the same as installing binaries in a
standard vs non-standard path - if the binaries are placed in a standard
location then they are found automatically, but if installed in a custom
location, then the user is responsible for ensuring all paths are correct.
/Bruce
On Tue, Jun 6, 2023 at 2:49 PM Bruce Richardson
<bruce.richardson@intel.com> wrote:
>
> On Mon, Jun 05, 2023 at 10:50:48AM +0530, Jerin Jacob wrote:
> > On Thu, Jun 1, 2023 at 9:08 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>
> >
> > > +
> > > +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)
> >
> > It does not look like just executing mandb it is adding these man
> > pages to database
> >
> > log:
> > Running custom install script '/usr/bin/mandb'
> > Purging old database entries in /home/jerin/.local/man...
> > Processing manual pages under /home/jerin/.local/man...
> > Checking for stray cats under /home/jerin/.local/man...
> > Processing manual pages under /home/jerin/.local/man/cat1...
> > Purging old database entries in /home/jerin/.local/share/man...
> > Processing manual pages under /home/jerin/.local/share/man...
> > Checking for stray cats under /home/jerin/.local/share/man...
> > Processing manual pages under /home/jerin/.local/share/man/cat1...
> > 0 man subdirectories contained newer manual pages.
> > 0 manual pages were added.
> > 0 stray cats were added.
> > 0 old database entries were purged.
> >
> > [main][dpdk.org] $ man rte_flow_create
> > No manual entry for rte_flow_create
> >
> > # Following works by providing the path i.e man pages created properly
> > only db update is missing
> > man --manpath=/tmp/i/usr/local/share/man/ rte_flow_create
> >
> Yes, that is correct.
>
> If you install to a non-standard location, then yes you need to update
> manpath yourself. However, in case you install to a "standard" location,
> then running mandb will update the database for you. I believe this is the
> behaviour we should have. I view it as the same as installing binaries in a
> standard vs non-standard path - if the binaries are placed in a standard
> location then they are found automatically, but if installed in a custom
> location, then the user is responsible for ensuring all paths are correct.
OK. Then I think, we can move "meson.add_install_script(mandb)"
invocation under !DESTDIR not provided.
As if DESTDIR is provided then there is no use for mandb.
>
> /Bruce
On Tue, Jun 06, 2023 at 03:16:27PM +0530, Jerin Jacob wrote:
> On Tue, Jun 6, 2023 at 2:49 PM Bruce Richardson
> <bruce.richardson@intel.com> wrote:
> >
> > On Mon, Jun 05, 2023 at 10:50:48AM +0530, Jerin Jacob wrote:
> > > On Thu, Jun 1, 2023 at 9:08 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>
> > >
> > > > +
> > > > +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)
> > >
> > > It does not look like just executing mandb it is adding these man
> > > pages to database
> > >
> > > log:
> > > Running custom install script '/usr/bin/mandb'
> > > Purging old database entries in /home/jerin/.local/man...
> > > Processing manual pages under /home/jerin/.local/man...
> > > Checking for stray cats under /home/jerin/.local/man...
> > > Processing manual pages under /home/jerin/.local/man/cat1...
> > > Purging old database entries in /home/jerin/.local/share/man...
> > > Processing manual pages under /home/jerin/.local/share/man...
> > > Checking for stray cats under /home/jerin/.local/share/man...
> > > Processing manual pages under /home/jerin/.local/share/man/cat1...
> > > 0 man subdirectories contained newer manual pages.
> > > 0 manual pages were added.
> > > 0 stray cats were added.
> > > 0 old database entries were purged.
> > >
> > > [main][dpdk.org] $ man rte_flow_create
> > > No manual entry for rte_flow_create
> > >
> > > # Following works by providing the path i.e man pages created properly
> > > only db update is missing
> > > man --manpath=/tmp/i/usr/local/share/man/ rte_flow_create
> > >
> > Yes, that is correct.
> >
> > If you install to a non-standard location, then yes you need to update
> > manpath yourself. However, in case you install to a "standard" location,
> > then running mandb will update the database for you. I believe this is the
> > behaviour we should have. I view it as the same as installing binaries in a
> > standard vs non-standard path - if the binaries are placed in a standard
> > location then they are found automatically, but if installed in a custom
> > location, then the user is responsible for ensuring all paths are correct.
>
> OK. Then I think, we can move "meson.add_install_script(mandb)"
> invocation under !DESTDIR not provided.
> As if DESTDIR is provided then there is no use for mandb.
>
That would mean adding a new build script to run mandb, since:
* meson doesn't directly support getting environment variables
* DESTDIR may only be set at install time rather than at configuration
time, so we'll always need to set up the build script
Furthermore, I'd point out that DESTDIR is not going to avoid unnecessary
runs of mandb, since using a special "prefix" setting would also cause the
manpages to not be found.
Overall, I'd view the complexity of avoiding the mandb call not to be
worth it, since calling mandb is largely harmless - bar the time taken to
run it. However, if you feel strongly it should be skipped when installing
with DESTDIR, I'll spin a v2 with the wrapper script added. Let me know
what you think?
/Bruce
On Tue, Jun 6, 2023 at 3:49 PM Bruce Richardson
<bruce.richardson@intel.com> wrote:
>
> On Tue, Jun 06, 2023 at 03:16:27PM +0530, Jerin Jacob wrote:
> > On Tue, Jun 6, 2023 at 2:49 PM Bruce Richardson
> > <bruce.richardson@intel.com> wrote:
> > >
> > > On Mon, Jun 05, 2023 at 10:50:48AM +0530, Jerin Jacob wrote:
> > > > On Thu, Jun 1, 2023 at 9:08 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>
> > > >
> > > > > +
> > > > > +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)
> > > >
> > > > It does not look like just executing mandb it is adding these man
> > > > pages to database
> > > >
> > > > log:
> > > > Running custom install script '/usr/bin/mandb'
> > > > Purging old database entries in /home/jerin/.local/man...
> > > > Processing manual pages under /home/jerin/.local/man...
> > > > Checking for stray cats under /home/jerin/.local/man...
> > > > Processing manual pages under /home/jerin/.local/man/cat1...
> > > > Purging old database entries in /home/jerin/.local/share/man...
> > > > Processing manual pages under /home/jerin/.local/share/man...
> > > > Checking for stray cats under /home/jerin/.local/share/man...
> > > > Processing manual pages under /home/jerin/.local/share/man/cat1...
> > > > 0 man subdirectories contained newer manual pages.
> > > > 0 manual pages were added.
> > > > 0 stray cats were added.
> > > > 0 old database entries were purged.
> > > >
> > > > [main][dpdk.org] $ man rte_flow_create
> > > > No manual entry for rte_flow_create
> > > >
> > > > # Following works by providing the path i.e man pages created properly
> > > > only db update is missing
> > > > man --manpath=/tmp/i/usr/local/share/man/ rte_flow_create
> > > >
> > > Yes, that is correct.
> > >
> > > If you install to a non-standard location, then yes you need to update
> > > manpath yourself. However, in case you install to a "standard" location,
> > > then running mandb will update the database for you. I believe this is the
> > > behaviour we should have. I view it as the same as installing binaries in a
> > > standard vs non-standard path - if the binaries are placed in a standard
> > > location then they are found automatically, but if installed in a custom
> > > location, then the user is responsible for ensuring all paths are correct.
> >
> > OK. Then I think, we can move "meson.add_install_script(mandb)"
> > invocation under !DESTDIR not provided.
> > As if DESTDIR is provided then there is no use for mandb.
> >
> That would mean adding a new build script to run mandb, since:
> * meson doesn't directly support getting environment variables
> * DESTDIR may only be set at install time rather than at configuration
> time, so we'll always need to set up the build script
>
> Furthermore, I'd point out that DESTDIR is not going to avoid unnecessary
> runs of mandb, since using a special "prefix" setting would also cause the
> manpages to not be found.
>
> Overall, I'd view the complexity of avoiding the mandb call not to be
> worth it, since calling mandb is largely harmless - bar the time taken to
> run it. However, if you feel strongly it should be skipped when installing
> with DESTDIR
No strong option. OK to skip DESTDIR check.
>, I'll spin a v2 with the wrapper script added. Let me know
> what you think?
I think, it is good to update doc/guides/contributing/documentation.rst
on how to use the man page(i.e use with --manpage)
>
> /Bruce
On Tue, Jun 06, 2023 at 04:19:27PM +0530, Jerin Jacob wrote:
> On Tue, Jun 6, 2023 at 3:49 PM Bruce Richardson
> <bruce.richardson@intel.com> wrote:
> >
> > On Tue, Jun 06, 2023 at 03:16:27PM +0530, Jerin Jacob wrote:
> > > On Tue, Jun 6, 2023 at 2:49 PM Bruce Richardson
> > > <bruce.richardson@intel.com> wrote:
> > > >
> > > > On Mon, Jun 05, 2023 at 10:50:48AM +0530, Jerin Jacob wrote:
> > > > > On Thu, Jun 1, 2023 at 9:08 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>
> > > > >
> > > > > > +
> > > > > > +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)
> > > > >
> > > > > It does not look like just executing mandb it is adding these man
> > > > > pages to database
> > > > >
> > > > > log:
> > > > > Running custom install script '/usr/bin/mandb'
> > > > > Purging old database entries in /home/jerin/.local/man...
> > > > > Processing manual pages under /home/jerin/.local/man...
> > > > > Checking for stray cats under /home/jerin/.local/man...
> > > > > Processing manual pages under /home/jerin/.local/man/cat1...
> > > > > Purging old database entries in /home/jerin/.local/share/man...
> > > > > Processing manual pages under /home/jerin/.local/share/man...
> > > > > Checking for stray cats under /home/jerin/.local/share/man...
> > > > > Processing manual pages under /home/jerin/.local/share/man/cat1...
> > > > > 0 man subdirectories contained newer manual pages.
> > > > > 0 manual pages were added.
> > > > > 0 stray cats were added.
> > > > > 0 old database entries were purged.
> > > > >
> > > > > [main][dpdk.org] $ man rte_flow_create
> > > > > No manual entry for rte_flow_create
> > > > >
> > > > > # Following works by providing the path i.e man pages created properly
> > > > > only db update is missing
> > > > > man --manpath=/tmp/i/usr/local/share/man/ rte_flow_create
> > > > >
> > > > Yes, that is correct.
> > > >
> > > > If you install to a non-standard location, then yes you need to update
> > > > manpath yourself. However, in case you install to a "standard" location,
> > > > then running mandb will update the database for you. I believe this is the
> > > > behaviour we should have. I view it as the same as installing binaries in a
> > > > standard vs non-standard path - if the binaries are placed in a standard
> > > > location then they are found automatically, but if installed in a custom
> > > > location, then the user is responsible for ensuring all paths are correct.
> > >
> > > OK. Then I think, we can move "meson.add_install_script(mandb)"
> > > invocation under !DESTDIR not provided.
> > > As if DESTDIR is provided then there is no use for mandb.
> > >
> > That would mean adding a new build script to run mandb, since:
> > * meson doesn't directly support getting environment variables
> > * DESTDIR may only be set at install time rather than at configuration
> > time, so we'll always need to set up the build script
> >
> > Furthermore, I'd point out that DESTDIR is not going to avoid unnecessary
> > runs of mandb, since using a special "prefix" setting would also cause the
> > manpages to not be found.
> >
> > Overall, I'd view the complexity of avoiding the mandb call not to be
> > worth it, since calling mandb is largely harmless - bar the time taken to
> > run it. However, if you feel strongly it should be skipped when installing
> > with DESTDIR
>
> No strong option. OK to skip DESTDIR check.
>
> >, I'll spin a v2 with the wrapper script added. Let me know
> > what you think?
>
> I think, it is good to update doc/guides/contributing/documentation.rst
> on how to use the man page(i.e use with --manpage)
>
Ok, will spin a v2.
@@ -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
@@ -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,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