From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 4199642FC8; Thu, 3 Aug 2023 18:44:16 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 2FC6B4161A; Thu, 3 Aug 2023 18:44:16 +0200 (CEST) Received: from mgamail.intel.com (mgamail.intel.com [134.134.136.126]) by mails.dpdk.org (Postfix) with ESMTP id CB567406BA for ; Thu, 3 Aug 2023 18:44:13 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1691081054; x=1722617054; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=0yV4cM3GpZFUKbG3BEhsR6iAsfS0SL2Tfq3rgaJmmmc=; b=FJoDbBqMitENtHhl61pvsv29QAsOCh0c5+3F5EL7UyH5HFrjgsbYOI3H Z8HWDKpJ9+tSgL4LKm5p9Yr0S1wqpV2+NkHCLv2VqEp2D/8+DIdxkheBR DmgiH3obW6nbxLPCYGNQse9JP8ea2xkYKIP3ylpgCsEfzNu6TNObN74dG VXHF6MCQUwnBiKdQjNseNoJLUghQuLPem1UwdW8Fn7FE0ai3swl4NwV+I 7zFc2dw5HwAGqUpvq0BbkbYCjs9/lY73SN5B9CaszkNh7T6Umj01Qfk8K 2lENHlX1c+bhXf6C2IW5c0O0OUecvxBiVJk9kLWvQHn4AZhB0scOKOhzo Q==; X-IronPort-AV: E=McAfee;i="6600,9927,10791"; a="354865039" X-IronPort-AV: E=Sophos;i="6.01,252,1684825200"; d="scan'208";a="354865039" Received: from orsmga006.jf.intel.com ([10.7.209.51]) by orsmga106.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 03 Aug 2023 09:44:11 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10791"; a="706619707" X-IronPort-AV: E=Sophos;i="6.01,252,1684825200"; d="scan'208";a="706619707" Received: from silpixa00401385.ir.intel.com ([10.237.214.162]) by orsmga006.jf.intel.com with ESMTP; 03 Aug 2023 09:44:10 -0700 From: Bruce Richardson To: dev@dpdk.org Cc: Bruce Richardson , David Marchand Subject: [PATCH v3] doc: build manpages as well as html output Date: Thu, 3 Aug 2023 17:44:00 +0100 Message-Id: <20230803164400.98873-1-bruce.richardson@intel.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230601153801.118616-1-bruce.richardson@intel.com> References: <20230601153801.118616-1-bruce.richardson@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit 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 Reviewed-by: David Marchand --- 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 | 54 +++++++++++++++++++---- doc/guides/contributing/documentation.rst | 12 ++++- 4 files changed, 63 insertions(+), 13 deletions(-) diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in index 1a4210b948..c77bdb328b 100644 --- a/doc/api/doxy-api.conf.in +++ b/doc/api/doxy-api.conf.in @@ -124,11 +124,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 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..9f83b34bb3 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,33 @@ 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') +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 +75,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 diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst index 7fcbb7fc43..e0b672ffbb 100644 --- a/doc/guides/contributing/documentation.rst +++ b/doc/guides/contributing/documentation.rst @@ -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:: -- 2.39.2