doc: make sphinx errors more visible
PATCH 1/1 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.
--- buildtools/call-sphinx-build.py | 3 +++ doc/guides/conf.py | 19 +++++++++++++++---- 2 files changed, 18 insertions(+), 4 deletions(-)
buildtools/call-sphinx-build.py +3 -0
@@ -14,6 +14,9 @@ # set the version in environment for sphinx to pick up os.environ['DPDK_VERSION'] = version +# forward error policy to conf.py +if '-W' in extra_args: + os.environ['SPHINX_STOP_ON_ERROR'] = 'true' # for sphinx version >= 1.7 add parallelism using "-j auto" ver = run([sphinx, '--version'], stdout=PIPE,
doc/guides/conf.py +15 -4
@@ -12,6 +12,7 @@ from os.path import basename from os.path import dirname from os.path import join as path_join +from sys import stderr import configparser
@@ -22,9 +23,12 @@ 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 = environ['SPHINX_STOP_ON_ERROR'] + 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.
Signature · 1 line
2.28.0
Quoted 21 lines · Thomas Monjalon
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.pywere 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 <[email protected]>--- buildtools/call-sphinx-build.py | 3 +++ doc/guides/conf.py | 19 +++++++++++++++---- 2 files changed, 18 insertions(+), 4 deletions(-)buildtools/call-sphinx-build.py +0
-0
buildtools/call-sphinx-build.py line 20
Quoted 7 lines
buildtools/call-sphinx-build.py +3
-0@@ -14,6 +14,9 @@ # set the version in environment for sphinx to pick up os.environ['DPDK_VERSION'] = version +# forward error policy to conf.py +if '-W' in extra_args: + os.environ['SPHINX_STOP_ON_ERROR'] = 'true'
Actually, I'm not sure this is necessary. Since the conf.py is processed from within the sphinx process itself, you can access sys.argv directly from within conf.py, rather than having to pass variables through the environment.
/Bruce
16/10/2020 11:18, Bruce Richardson:
Quoted 23 lines · Thomas Monjalon
Quoted 22 lines
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.pywere 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 <[email protected]>--- buildtools/call-sphinx-build.py | 3 +++ doc/guides/conf.py | 19 +++++++++++++++---- 2 files changed, 18 insertions(+), 4 deletions(-)buildtools/call-sphinx-build.py +0
-0@@ -14,6 +14,9 @@
Quoted 11 lines
buildtools/call-sphinx-build.py line 20
Quoted 6 lines
buildtools/call-sphinx-build.py +3
-0# set the version in environment for sphinx to pick up os.environ['DPDK_VERSION'] = version +# forward error policy to conf.py +if '-W' in extra_args: + os.environ['SPHINX_STOP_ON_ERROR'] = 'true'Actually, I'm not sure this is necessary. Since the
conf.pyis processed from within the sphinx process itself, you can access sys.argv directly from withinconf.py, rather than having to pass variables through the environment.
Great idea, thanks
PATCH v2 1/1 doc: make sphinx errors more visible
In reply to Thomas MonjalonWhen 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.
---
v2: check -W option directly from Sphinx argv
--- doc/guides/conf.py | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-)
doc/guides/conf.py +15 -4
@@ -12,6 +12,7 @@ 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 @@ 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.
Signature · 1 line
2.28.0
Quoted 4 lines · Thomas Monjalon
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.
Quoted 8 lines
Some warnings generated by the
conf.pywere 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 <[email protected]>---
LGTM anyway
Thomas Monjalon
Applied16/10/2020 14:43, Bruce Richardson:
Quoted 11 lines · Thomas Monjalon
Quoted 10 lines
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.pywere 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.
Quoted 6 lines
Quoted 2 lines
Signed-off-by Thomas Monjalon <[email protected]>---
LGTM anyway
Acked-by Bruce Richardson <[email protected]>
Applied