From: Bruce Richardson <bruce.richardson@intel.com>
To: dev@dpdk.org
Cc: Bruce Richardson <bruce.richardson@intel.com>
Subject: [PATCH] doc: build manpages as well as html output
Date: Thu, 1 Jun 2023 16:38:01 +0100 [thread overview]
Message-ID: <20230601153801.118616-1-bruce.richardson@intel.com> (raw)
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(-)
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
--
2.39.2
next reply other threads:[~2023-06-01 15:38 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-06-01 15:38 Bruce Richardson [this message]
2023-06-05 5:20 ` Jerin Jacob
2023-06-06 9:18 ` Bruce Richardson
2023-06-06 9:46 ` Jerin Jacob
2023-06-06 10:18 ` Bruce Richardson
2023-06-06 10:49 ` Jerin Jacob
2023-06-06 10:54 ` Bruce Richardson
2023-06-06 13:12 ` [PATCH v2] " Bruce Richardson
2023-07-04 8:21 ` David Marchand
2023-07-17 11:09 ` Bruce Richardson
2023-08-03 9:18 ` David Marchand
2023-08-03 16:43 ` Bruce Richardson
2023-08-03 16:44 ` [PATCH v3] " Bruce Richardson
2023-08-04 12:12 ` David Marchand
2023-08-29 9:28 ` Thomas Monjalon
2023-08-29 10:10 ` Bruce Richardson
2023-08-30 9:47 ` Thomas Monjalon
2023-08-30 10:20 ` Bruce Richardson
2023-08-30 11:23 ` Thomas Monjalon
2023-08-31 9:49 ` [PATCH v4] " Bruce Richardson
2023-08-31 10:12 ` Thomas Monjalon
2023-08-31 15:48 ` Morten Brørup
2023-09-27 16:25 ` Thomas Monjalon
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230601153801.118616-1-bruce.richardson@intel.com \
--to=bruce.richardson@intel.com \
--cc=dev@dpdk.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).