From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id D7284A04F9; Fri, 10 Jan 2020 22:52:52 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 641941EBE8; Fri, 10 Jan 2020 22:52:25 +0100 (CET) Received: from mga07.intel.com (mga07.intel.com [134.134.136.100]) by dpdk.org (Postfix) with ESMTP id D796A1EC0A for ; Fri, 10 Jan 2020 22:52:23 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga002.fm.intel.com ([10.253.24.26]) by orsmga105.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 10 Jan 2020 13:52:23 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.69,418,1571727600"; d="scan'208";a="255163014" Received: from silpixa00399126.ir.intel.com (HELO silpixa00399126.ger.corp.intel.com) ([10.237.223.2]) by fmsmga002.fm.intel.com with ESMTP; 10 Jan 2020 13:52:21 -0800 From: Bruce Richardson To: david.marchand@redhat.com, john.mcnamara@intel.com, bluca@debian.org Cc: dev@dpdk.org, aconole@redhat.com, thomas@monjalon.net, Bruce Richardson Date: Fri, 10 Jan 2020 21:52:04 +0000 Message-Id: <20200110215205.513185-6-bruce.richardson@intel.com> X-Mailer: git-send-email 2.24.1 In-Reply-To: <20200110215205.513185-1-bruce.richardson@intel.com> References: <20200109115631.500056-1-bruce.richardson@intel.com> <20200110215205.513185-1-bruce.richardson@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH v4 5/6] doc/guides: rebuild with meson whenever a file changes X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Add proper support for calling sphinx whenever a file in the doc directory changes. This is accomplished by using a wrapper script for sphinx, which runs sphinx but also emits a gcc-format dependency file listing all the doc files. This is used by ninja so that any change to the doc files triggers a rebuild of the docs. Signed-off-by: Bruce Richardson Acked-by: Aaron Conole Acked-by: Luca Boccassi --- MAINTAINERS | 1 + buildtools/call-sphinx-build.py | 31 +++++++++++++++++++++++++++++++ buildtools/meson.build | 6 ++++-- doc/guides/meson.build | 22 ++++++++-------------- 4 files changed, 44 insertions(+), 16 deletions(-) create mode 100755 buildtools/call-sphinx-build.py diff --git a/MAINTAINERS b/MAINTAINERS index 4395d8df1..aa32bfc59 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -128,6 +128,7 @@ F: meson.build F: lib/librte_eal/freebsd/BSDmakefile.meson F: meson_options.txt F: config/rte_config.h +F: buildtools/call-sphinx-build.py F: buildtools/gen-pmdinfo-cfile.sh F: buildtools/map_to_def.py F: buildtools/symlink-drivers-solibs.sh diff --git a/buildtools/call-sphinx-build.py b/buildtools/call-sphinx-build.py new file mode 100755 index 000000000..b9a3994e1 --- /dev/null +++ b/buildtools/call-sphinx-build.py @@ -0,0 +1,31 @@ +#! /usr/bin/env python3 +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2019 Intel Corporation +# + +import sys +import os +from os.path import join +from subprocess import run, PIPE +from distutils.version import StrictVersion + +(sphinx, src, dst) = sys.argv[1:] # assign parameters to variables + +# for sphinx version >= 1.7 add parallelism using "-j auto" +ver = run([sphinx, '--version'], stdout=PIPE).stdout.decode().split()[-1] +sphinx_cmd = [sphinx] +if StrictVersion(ver) >= StrictVersion('1.7'): + sphinx_cmd += ['-j', 'auto'] + +# find all the files sphinx will process so we can write them as dependencies +srcfiles = [] +for root, dirs, files in os.walk(src): + srcfiles.extend([join(root, f) for f in files]) + +# run sphinx, putting the html output in a "html" directory +process = run(sphinx_cmd + ['-b', 'html', src, join(dst, 'html')], check=True) +print(str(process.args) + ' Done OK') + +# create a gcc format .d file giving all the dependencies of this doc build +with open(join(dst, '.html.d'), 'w') as d: + d.write('html: ' + ' '.join(srcfiles) + '\n') diff --git a/buildtools/meson.build b/buildtools/meson.build index 6ef2c5721..cd1d05403 100644 --- a/buildtools/meson.build +++ b/buildtools/meson.build @@ -10,10 +10,12 @@ check_experimental_syms = find_program('check-experimental-syms.sh') # set up map-to-def script using python, either built-in or external python3 = import('python').find_installation(required: false) if python3.found() - map_to_def_cmd = [python3, files('map_to_def.py')] + py3 = [python3] else - map_to_def_cmd = ['meson', 'runpython', files('map_to_def.py')] + py3 = ['meson', 'runpython'] endif +map_to_def_cmd = py3 + files('map_to_def.py') +sphinx_wrapper = py3 + files('call-sphinx-build.py') # stable ABI always starts with "DPDK_" is_experimental_cmd = [find_program('grep', 'findstr'), '^DPDK_'] diff --git a/doc/guides/meson.build b/doc/guides/meson.build index 80c21d168..732e7ad3a 100644 --- a/doc/guides/meson.build +++ b/doc/guides/meson.build @@ -7,24 +7,18 @@ if not sphinx.found() subdir_done() endif -htmldir = join_paths('share', 'doc', 'dpdk') +htmldir = join_paths(get_option('datadir'), 'doc', 'dpdk') html_guides = custom_target('html_guides', - input: meson.current_source_dir(), - output: 'guides', - command: [sphinx, '-b', 'html', - '-d', meson.current_build_dir() + '/.doctrees', - '@INPUT@', meson.current_build_dir() + '/guides'], + input: files('index.rst'), + output: 'html', + command: [sphinx_wrapper, sphinx, meson.current_source_dir(), meson.current_build_dir()], + depfile: '.html.d', build_by_default: get_option('enable_docs'), install: get_option('enable_docs'), install_dir: htmldir) +install_data(files('custom.css'), + install_dir: join_paths(htmldir,'_static', 'css')) + doc_targets += html_guides doc_target_names += 'HTML_Guides' - -# sphinx leaves a .buildinfo in the target directory, which we don't -# want to install. Note that sh -c has to be used, otherwise the -# env var does not get expanded if calling rm/install directly. -meson.add_install_script('sh', '-c', - 'rm -f $MESON_INSTALL_DESTDIR_PREFIX/share/doc/dpdk/guides/.buildinfo') -meson.add_install_script('sh', '-c', - 'install -D -m0644 $MESON_SOURCE_ROOT/doc/guides/custom.css $MESON_INSTALL_DESTDIR_PREFIX/share/doc/dpdk/guides/_static/css/custom.css') -- 2.24.1