[v2] 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>
---
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(-)
Comments
On Tue, Jun 6, 2023 at 3:13 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>
Nice.. we should have done this sooner :-).
Reviewed-by: David Marchand <david.marchand@redhat.com>
There may be some polishing to do later.
Looking at the result for rte_eal_init, I see that the generated
manual starts with a reference to the rte_eal.h header with a path
relative to its location in the DPDK tree.
$ MANPATH=build-gcc/install/share/man man rte_eal_init | head -5
lib/eal/include/rte_eal.h(3)
DPDK
lib/eal/include/rte_eal.h(3)
NAME
lib/eal/include/rte_eal.h
At least, it is possible to ask for this header man with "man
rte_eal.h", but it is a bit confusing.
Is there something we can do on this side?
On Tue, Jul 04, 2023 at 10:21:22AM +0200, David Marchand wrote:
> On Tue, Jun 6, 2023 at 3:13 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>
>
> Nice.. we should have done this sooner :-).
>
> Reviewed-by: David Marchand <david.marchand@redhat.com>
>
>
> There may be some polishing to do later.
> Looking at the result for rte_eal_init, I see that the generated
> manual starts with a reference to the rte_eal.h header with a path
> relative to its location in the DPDK tree.
> $ MANPATH=build-gcc/install/share/man man rte_eal_init | head -5
> lib/eal/include/rte_eal.h(3)
> DPDK
>
> lib/eal/include/rte_eal.h(3)
>
> NAME
> lib/eal/include/rte_eal.h
>
> At least, it is possible to ask for this header man with "man
> rte_eal.h", but it is a bit confusing.
> Is there something we can do on this side?
>
Not sure, not really familiar with how doxygen works generating manpages
and the options supported, etc. etc. Mainly I just looked at the
build-system side to support this, since I really missed having manpages
for DPDK functions to quickly check parameter order.
/Bruce
On Mon, Jul 17, 2023 at 1:09 PM Bruce Richardson
<bruce.richardson@intel.com> wrote:
> > There may be some polishing to do later.
> > Looking at the result for rte_eal_init, I see that the generated
> > manual starts with a reference to the rte_eal.h header with a path
> > relative to its location in the DPDK tree.
> > $ MANPATH=build-gcc/install/share/man man rte_eal_init | head -5
> > lib/eal/include/rte_eal.h(3)
> > DPDK
> >
> > lib/eal/include/rte_eal.h(3)
> >
> > NAME
> > lib/eal/include/rte_eal.h
> >
> > At least, it is possible to ask for this header man with "man
> > rte_eal.h", but it is a bit confusing.
> > Is there something we can do on this side?
> >
>
> Not sure, not really familiar with how doxygen works generating manpages
> and the options supported, etc. etc. Mainly I just looked at the
> build-system side to support this, since I really missed having manpages
> for DPDK functions to quickly check parameter order.
doxygen is invoked on the sources tree, so this is probably the reason
why such path is in the generated manual.
Maybe Thomas has an idea how we could handle this.
In any case, I am fine with this patch as it is now.
On Thu, Aug 03, 2023 at 11:18:09AM +0200, David Marchand wrote:
> On Mon, Jul 17, 2023 at 1:09 PM Bruce Richardson
> <bruce.richardson@intel.com> wrote:
> > > There may be some polishing to do later.
> > > Looking at the result for rte_eal_init, I see that the generated
> > > manual starts with a reference to the rte_eal.h header with a path
> > > relative to its location in the DPDK tree.
> > > $ MANPATH=build-gcc/install/share/man man rte_eal_init | head -5
> > > lib/eal/include/rte_eal.h(3)
> > > DPDK
> > >
> > > lib/eal/include/rte_eal.h(3)
> > >
> > > NAME
> > > lib/eal/include/rte_eal.h
> > >
> > > At least, it is possible to ask for this header man with "man
> > > rte_eal.h", but it is a bit confusing.
> > > Is there something we can do on this side?
> > >
> >
> > Not sure, not really familiar with how doxygen works generating manpages
> > and the options supported, etc. etc. Mainly I just looked at the
> > build-system side to support this, since I really missed having manpages
> > for DPDK functions to quickly check parameter order.
>
> doxygen is invoked on the sources tree, so this is probably the reason
> why such path is in the generated manual.
> Maybe Thomas has an idea how we could handle this.
>
> In any case, I am fine with this patch as it is now.
>
I think I've found a fix for this.
doxygen setting "FULL_PATH_NAMES" defaults to "YES", which is what we want
for the HTML pages. However, setting it to "NO", I believe is correct for
generating the manpages.
Patch V3 on its way.
/Bruce
@@ -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
@@ -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::