Skip to contentSkip to conversation

doc: make sphinx comply with meson werror option

PATCH Applied Bruce Richardson 2 participants 2 messages Oct 1, 2020 – Oct 5, 2020 Arm/Amlogic Meson SoC support

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 doc: make sphinx comply with meson werror option

When the --werror meson build option is set, we can pass the "-W", warning-as-errors, flag to sphinx to get the same behaviour for doc building as for building the rest of DPDK. This can help catch documentation errors sooner in the development process.

---
NOTE: to avoid breaking the build, this patch naturally requires all doc warnings to have been fixed before apply.

---
 buildtools/call-sphinx-build.py | 8 +++++---
 doc/guides/meson.build          | 8 +++++++-
 2 files changed, 12 insertions(+), 4 deletions(-)
buildtools/call-sphinx-build.py +5 -3
index 0dce59f641..26b199220a 100755
@@ -9,7 +9,8 @@
 from subprocess import run, PIPE, STDOUT
 from distutils.version import StrictVersion
 
-(sphinx, version, src, dst) = sys.argv[1:]  # assign parameters to variables
+# assign parameters to variables
+(sphinx, version, src, dst, *extra_args) = sys.argv[1:]
 
 # set the version in environment for sphinx to pick up
 os.environ['DPDK_VERSION'] = version
@@ -17,7 +18,7 @@
 # for sphinx version >= 1.7 add parallelism using "-j auto"
 ver = run([sphinx, '--version'], stdout=PIPE,
           stderr=STDOUT).stdout.decode().split()[-1]
-sphinx_cmd = [sphinx]
+sphinx_cmd = [sphinx] + extra_args
 if StrictVersion(ver) >= StrictVersion('1.7'):
     sphinx_cmd += ['-j', 'auto']
 
@@ -29,9 +30,10 @@
 # run sphinx, putting the html output in a "html" directory
 with open(join(dst, 'sphinx_html.out'), 'w') as out:
     process = run(sphinx_cmd + ['-b', 'html', src, join(dst, 'html')],
-                  check=True,
                   stdout=out)
 
 # 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')
+
+sys.exit(process.returncode)
doc/guides/meson.build +7 -1
index daab139c4e..9c35efb5b2 100644
@@ -7,12 +7,18 @@ if not sphinx.found()
 	subdir_done()
 endif
 
+extra_sphinx_args = []
+if get_option('werror')
+	extra_sphinx_args += '-W'
+endif
+
 htmldir = join_paths(get_option('datadir'), 'doc', 'dpdk')
 html_guides = custom_target('html_guides',
 	input: files('index.rst'),
 	output: 'html',
 	command: [sphinx_wrapper, sphinx, meson.project_version(),
-		meson.current_source_dir(), meson.current_build_dir()],
+		meson.current_source_dir(), meson.current_build_dir(),
+		extra_sphinx_args],
 	depfile: '.html.d',
 	build_by_default: get_option('enable_docs'),
 	install: get_option('enable_docs'),
Signature · 1 line
2.25.1
#1 lore raw
Quoted 6 lines

When the --werror meson build option is set, we can pass the "-W", warning-as-errors, flag to sphinx to get the same behaviour for doc building as for building the rest of DPDK. This can help catch documentation errors sooner in the development process.

Applied, thanks