[v2] doc: make sphinx errors more visible
Checks
Commit Message
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 <thomas@monjalon.net>
---
v2: check -W option directly from Sphinx argv
---
doc/guides/conf.py | 19 +++++++++++++++----
1 file changed, 15 insertions(+), 4 deletions(-)
Comments
On Fri, Oct 16, 2020 at 02:39:06PM +0200, Thomas Monjalon wrote:
> 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 <thomas@monjalon.net>
> ---
LGTM anyway
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
16/10/2020 14:43, Bruce Richardson:
> On Fri, Oct 16, 2020 at 02:39:06PM +0200, Thomas Monjalon wrote:
> > 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 <thomas@monjalon.net>
> > ---
>
> LGTM anyway
>
> Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Applied
@@ -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.