[dpdk-stable] patch 'doc: rebuild with meson whenever a file changes' has been queued to stable release 19.11.4

[luca.boccassi at gmail.com]

Hi,

FYI, your patch has been queued to stable release 19.11.4

Note it hasn't been pushed to http://dpdk.org/browse/dpdk-stable yet.
It will be pushed if I get no objections before 07/26/20. So please
shout if anyone has objections.

Also note that after the patch there's a diff of the upstream commit vs the
patch applied to the branch. This will indicate if there was any rebasing
needed to apply to the stable branch. If there were code changes for rebasing
(ie: not only metadata diffs), please double check that the rebase was
correctly done.

Thanks.

Luca Boccassi

---
>From d5a143fbcbb7fd84ee5269f5789c54cc952541a6 Mon Sep 17 00:00:00 2001
From: Bruce Richardson <bruce.richardson at intel.com>
Date: Fri, 10 Jan 2020 21:52:04 +0000
Subject: [PATCH] doc: rebuild with meson whenever a file changes

[ backported from upstream commit f5ab2074cfba1fa9287269aec08358c29799bc13 ]

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 <bruce.richardson at intel.com>
Acked-by: Aaron Conole <aconole at redhat.com>
Acked-by: Luca Boccassi <bluca at debian.org>
---
 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 98c0dd060..c9b7dfaca 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 cd6f4c1af..ea13d9fc3 100644
--- a/buildtools/meson.build
+++ b/buildtools/meson.build
@@ -12,10 +12,12 @@ ldflags_ibverbs_static = find_program('options-ibverbs-static.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.20.1