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 3895042C40; Tue, 6 Jun 2023 15:12:56 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 0BFA7406B3; Tue, 6 Jun 2023 15:12:56 +0200 (CEST) Received: from mga04.intel.com (mga04.intel.com [192.55.52.120]) by mails.dpdk.org (Postfix) with ESMTP id 4E42B40697 for ; Tue, 6 Jun 2023 15:12:54 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1686057174; x=1717593174; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=161qgtbBmoidNj/GZeu09WnnoeDVxqZuBVHv1evVYks=; b=W5CQtE7kOr7EAWvmznqYXEgCS+mKQrkG1ulGt98I56glofsrXUKh8o5Q ixJUy3k3vcJlPfz6auhsnnHalau+eYigZkHRiyUFS54XorbMeCiUNWaqR I3f8uUysEy7WRXbIvF7CscGZXl8NCH0EYxl7MOFIIir7DiXHv6GXLkLll GNBDO5q8T1fU+Xi8MtbzXNpm9jJ7+9XqpmY7fLNS0C35szhYrsi7P5srk 3j+mo8QXuzb7Xj9qCimjcbUiW2A1MsLhlHDTTkJRyXJhLqg4dMOblH/w2 4E1zVG29K76oK89kvoC2I8DxsuwaiLrg4Evx22iIr1D2jruZjjkKqKngj g==; X-IronPort-AV: E=McAfee;i="6600,9927,10732"; a="355519135" X-IronPort-AV: E=Sophos;i="6.00,221,1681196400"; d="scan'208";a="355519135" Received: from orsmga004.jf.intel.com ([10.7.209.38]) by fmsmga104.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 06 Jun 2023 06:12:53 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10732"; a="833225033" X-IronPort-AV: E=Sophos;i="6.00,221,1681196400"; d="scan'208";a="833225033" Received: from silpixa00401385.ir.intel.com ([10.237.214.11]) by orsmga004.jf.intel.com with ESMTP; 06 Jun 2023 06:12:51 -0700 From: Bruce Richardson To: dev@dpdk.org Cc: jerinjacobk@gmail.com, Bruce Richardson Subject: [PATCH v2] doc: build manpages as well as html output Date: Tue, 6 Jun 2023 14:12:30 +0100 Message-Id: <20230606131230.70428-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 --- 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(-) 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 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