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 1A54341FDA; Thu, 31 Aug 2023 11:49:50 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id A58504027B; Thu, 31 Aug 2023 11:49:49 +0200 (CEST) Received: from mgamail.intel.com (mgamail.intel.com [192.55.52.43]) by mails.dpdk.org (Postfix) with ESMTP id 459A240279 for ; Thu, 31 Aug 2023 11:49:48 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1693475388; x=1725011388; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=HDodyqoEQnVtSIJdbfQCYNoFlVHUJC0l2C/Om3tKUxE=; b=FbQCAvgAtXf9hjTEUwlc5A7ZtMDExTMnHYJ0RYw4OdZWF6TkBTyXpwgv 3fDY/VVDBvU2I+wIfaervYdI24mn7OBM6KCTXfcw2Nguzr5attIBJNbHf Rw4DeDy82zx1mMP0zp+D0J1J6aFnuOBPA7oWgn3kHRV8fuzFhevgsRKlr LqrjQu9iOEApUwOMA6BO0f5EdQygVmAheW52gp4hEpPYKhkpGCKv7mKq2 UDhUSuCwxjmVpOzRaK/WvoTuYqOf+1kgjRSoor7Tr8UtIxLGQhCCLTMvz VDG2piYg4AhyIgtvcT1Y7Ep1XF1qiZAz2egtusbJz4aOgWSsFWbc8xlaf A==; X-IronPort-AV: E=McAfee;i="6600,9927,10818"; a="462258065" X-IronPort-AV: E=Sophos;i="6.02,216,1688454000"; d="scan'208";a="462258065" Received: from orsmga003.jf.intel.com ([10.7.209.27]) by fmsmga105.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 31 Aug 2023 02:49:46 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10818"; a="689260206" X-IronPort-AV: E=Sophos;i="6.02,216,1688454000"; d="scan'208";a="689260206" Received: from silpixa00401385.ir.intel.com ([10.237.214.14]) by orsmga003.jf.intel.com with ESMTP; 31 Aug 2023 02:49:44 -0700 From: Bruce Richardson To: dev@dpdk.org Cc: thomas@monjalon.net, Bruce Richardson , David Marchand Subject: [PATCH v4] doc: build manpages as well as html output Date: Thu, 31 Aug 2023 10:49:33 +0100 Message-Id: <20230831094933.8124-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. If the manpages are not installed in system location i.e. one not in MANPATH, then this update will have no effect, as only system locations are scanned. Signed-off-by: Bruce Richardson Reviewed-by: David Marchand --- V4: fix whitespace issues. add clarifying notes about mandb updating the database by scanning system locations only. 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 | 58 +++++++++++++++++++---- doc/guides/contributing/documentation.rst | 12 ++++- 4 files changed, 67 insertions(+), 13 deletions(-) diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in index a88accd907..1ba72e6221 100644 --- a/doc/api/doxy-api.conf.in +++ b/doc/api/doxy-api.conf.in @@ -123,11 +123,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..8b0ced423b 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,35 @@ 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') +# for manpages, have the pages only titled with the header name, +# rather than the full path to the header +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 +77,26 @@ 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)' + +# refresh the manpage database on install +# if DPDK manpages are installed to a staging directory, not in MANPATH, this has no effect +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 79616e5610..4eb62fc36a 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