From patchwork Thu Jun 1 15:38:01 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 127870 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 1DD0642C05; Thu, 1 Jun 2023 17:38:30 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id F1FC140EF0; Thu, 1 Jun 2023 17:38:29 +0200 (CEST) Received: from mga06.intel.com (mga06b.intel.com [134.134.136.31]) by mails.dpdk.org (Postfix) with ESMTP id E78CC40DDC for ; Thu, 1 Jun 2023 17:38:28 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1685633909; x=1717169909; h=from:to:cc:subject:date:message-id:mime-version: content-transfer-encoding; bh=YizPWPrscZYEi9BhVJZTR41UWL7wvz9+38j30gafhNc=; b=LDquoi4RzIPW7wjFQdAFaF6DszNXw1Nvw33pcB+Bu0UijG3Ct0EAuiB+ RBgEIlZz8qlHcW5NQ3Dmtow7yLiMbRTVnpOrEHEn/lE0b6oHMSyAVKABC 058M1VeozYtjn1o7rv8I1Q2fR96uQ0fGUCrhV7TF/vkkX1ofE8l4syK57 KBUt6Z6X63CowtM/ShTUajIa4kwhjee82p2pdLVXW9YQF7NDNuVv8/dIW rgpn6Ydbw+eWlTtV5A1lIKNXaleSlngVe6hw2HDSycxNgWg89RUdy43fW /XPVUktooAkl+xtn5CH8e8IQCVNSscpMhlQ/rlRcb2tmav89IaDz6OTV+ w==; X-IronPort-AV: E=McAfee;i="6600,9927,10728"; a="419114963" X-IronPort-AV: E=Sophos;i="6.00,210,1681196400"; d="scan'208";a="419114963" Received: from orsmga005.jf.intel.com ([10.7.209.41]) by orsmga104.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 01 Jun 2023 08:38:25 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10728"; a="881664839" X-IronPort-AV: E=Sophos;i="6.00,210,1681196400"; d="scan'208";a="881664839" Received: from silpixa00401385.ir.intel.com ([10.237.214.11]) by orsmga005.jf.intel.com with ESMTP; 01 Jun 2023 08:38:24 -0700 From: Bruce Richardson To: dev@dpdk.org Cc: Bruce Richardson Subject: [PATCH] doc: build manpages as well as html output Date: Thu, 1 Jun 2023 16:38:01 +0100 Message-Id: <20230601153801.118616-1-bruce.richardson@intel.com> X-Mailer: git-send-email 2.39.2 MIME-Version: 1.0 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org 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 --- 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