From 028c57407df4288f061698b95336a9e9a0cf75b3 Mon Sep 17 00:00:00 2001 From: Thomas Monjalon Date: Fri, 16 Oct 2020 05:05:49 +0200 Subject: [PATCH] doc: make sphinx errors more visible When running Sphinx through ninja, the wrapper configured in meson redirects stdout to a log file. It makes more important to print issues on stderr. Some warnings generated by the conf.py were hidden because printed on stdout. The first improvement is to print them on stderr. The second measure is to stop processing if meson was configured with --werror. Signed-off-by: Thomas Monjalon Acked-by: Bruce Richardson --- doc/guides/conf.py | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/doc/guides/conf.py b/doc/guides/conf.py index 2ffe5a5969..9de490e1c4 100644 --- a/doc/guides/conf.py +++ b/doc/guides/conf.py @@ -12,6 +12,7 @@ from os import environ from os.path import basename from os.path import dirname from os.path import join as path_join +from sys import argv, stderr import configparser @@ -22,9 +23,12 @@ try: html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] except: print('Install the sphinx ReadTheDocs theme for improved html documentation ' - 'layout: https://sphinx-rtd-theme.readthedocs.io/') + 'layout: https://sphinx-rtd-theme.readthedocs.io/', + file=stderr) pass +stop_on_error = ('-W' in argv) + project = 'Data Plane Development Kit' html_logo = '../logo/DPDK_logo_vertical_rev_small.png' latex_logo = '../logo/DPDK_logo_horizontal_tag.png' @@ -217,7 +221,10 @@ def generate_overview_table(output_filename, table_id, section, table_name, titl if not config.has_section(section): print("{}: File '{}' has no [{}] secton".format(warning, ini_filename, - section)) + section), + file=stderr) + if stop_on_error: + raise Exception('Warning is treated as a failure') continue # Check for valid features names. @@ -225,7 +232,10 @@ def generate_overview_table(output_filename, table_id, section, table_name, titl if name not in valid_features: print("{}: Unknown feature '{}' in '{}'".format(warning, name, - ini_filename)) + ini_filename), + file=stderr) + if stop_on_error: + raise Exception('Warning is treated as a failure') continue if value: @@ -418,7 +428,8 @@ def setup(app): if LooseVersion(sphinx_version) < LooseVersion('1.3.1'): print('Upgrade sphinx to version >= 1.3.1 for ' - 'improved Figure/Table number handling.') + 'improved Figure/Table number handling.', + file=stderr) # Add a role to handle :numref: references. app.add_role('numref', numref_role) # Process the numref references once the doctree has been created. -- 2.20.1