DPDK patches and discussions
 help / color / Atom feed
* [dpdk-dev] [PATCH] doc: make sphinx errors more visible
@ 2020-10-16  3:39 Thomas Monjalon
  2020-10-16  9:18 ` Bruce Richardson
  2020-10-16 12:39 ` [dpdk-dev] [PATCH v2] " Thomas Monjalon
  0 siblings, 2 replies; 6+ messages in thread
From: Thomas Monjalon @ 2020-10-16  3:39 UTC (permalink / raw)
  To: dev; +Cc: david.marchand, bruce.richardson

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>
---
 buildtools/call-sphinx-build.py |  3 +++
 doc/guides/conf.py              | 19 +++++++++++++++----
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/buildtools/call-sphinx-build.py b/buildtools/call-sphinx-build.py
index 26b199220a..8b266bec9b 100755
--- a/buildtools/call-sphinx-build.py
+++ b/buildtools/call-sphinx-build.py
@@ -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,
diff --git a/doc/guides/conf.py b/doc/guides/conf.py
index 2ffe5a5969..ce91b9e658 100644
--- a/doc/guides/conf.py
+++ b/doc/guides/conf.py
@@ -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.
-- 
2.28.0


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [dpdk-dev] [PATCH] doc: make sphinx errors more visible
  2020-10-16  3:39 [dpdk-dev] [PATCH] doc: make sphinx errors more visible Thomas Monjalon
@ 2020-10-16  9:18 ` Bruce Richardson
  2020-10-16  9:27   ` Thomas Monjalon
  2020-10-16 12:39 ` [dpdk-dev] [PATCH v2] " Thomas Monjalon
  1 sibling, 1 reply; 6+ messages in thread
From: Bruce Richardson @ 2020-10-16  9:18 UTC (permalink / raw)
  To: Thomas Monjalon; +Cc: dev, david.marchand

On Fri, Oct 16, 2020 at 05:39:55AM +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>
> ---
>  buildtools/call-sphinx-build.py |  3 +++
>  doc/guides/conf.py              | 19 +++++++++++++++----
>  2 files changed, 18 insertions(+), 4 deletions(-)
> 
> diff --git a/buildtools/call-sphinx-build.py b/buildtools/call-sphinx-build.py
> index 26b199220a..8b266bec9b 100755
> --- a/buildtools/call-sphinx-build.py
> +++ b/buildtools/call-sphinx-build.py
> @@ -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


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [dpdk-dev] [PATCH] doc: make sphinx errors more visible
  2020-10-16  9:18 ` Bruce Richardson
@ 2020-10-16  9:27   ` Thomas Monjalon
  0 siblings, 0 replies; 6+ messages in thread
From: Thomas Monjalon @ 2020-10-16  9:27 UTC (permalink / raw)
  To: Bruce Richardson; +Cc: dev, david.marchand

16/10/2020 11:18, Bruce Richardson:
> On Fri, Oct 16, 2020 at 05:39:55AM +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>
> > ---
> >  buildtools/call-sphinx-build.py |  3 +++
> >  doc/guides/conf.py              | 19 +++++++++++++++----
> >  2 files changed, 18 insertions(+), 4 deletions(-)
> > 
> > diff --git a/buildtools/call-sphinx-build.py b/buildtools/call-sphinx-build.py
> > index 26b199220a..8b266bec9b 100755
> > --- a/buildtools/call-sphinx-build.py
> > +++ b/buildtools/call-sphinx-build.py
> > @@ -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.

Great idea, thanks



^ permalink raw reply	[flat|nested] 6+ messages in thread

* [dpdk-dev] [PATCH v2] doc: make sphinx errors more visible
  2020-10-16  3:39 [dpdk-dev] [PATCH] doc: make sphinx errors more visible Thomas Monjalon
  2020-10-16  9:18 ` Bruce Richardson
@ 2020-10-16 12:39 ` " Thomas Monjalon
  2020-10-16 12:43   ` Bruce Richardson
  1 sibling, 1 reply; 6+ messages in thread
From: Thomas Monjalon @ 2020-10-16 12:39 UTC (permalink / raw)
  To: dev; +Cc: david.marchand, bruce.richardson

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(-)

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.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.
-- 
2.28.0


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [dpdk-dev] [PATCH v2] doc: make sphinx errors more visible
  2020-10-16 12:39 ` [dpdk-dev] [PATCH v2] " Thomas Monjalon
@ 2020-10-16 12:43   ` Bruce Richardson
  2020-10-16 15:57     ` Thomas Monjalon
  0 siblings, 1 reply; 6+ messages in thread
From: Bruce Richardson @ 2020-10-16 12:43 UTC (permalink / raw)
  To: Thomas Monjalon; +Cc: dev, david.marchand

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>

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [dpdk-dev] [PATCH v2] doc: make sphinx errors more visible
  2020-10-16 12:43   ` Bruce Richardson
@ 2020-10-16 15:57     ` Thomas Monjalon
  0 siblings, 0 replies; 6+ messages in thread
From: Thomas Monjalon @ 2020-10-16 15:57 UTC (permalink / raw)
  To: dev; +Cc: david.marchand, Bruce Richardson

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




^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, back to index

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-10-16  3:39 [dpdk-dev] [PATCH] doc: make sphinx errors more visible Thomas Monjalon
2020-10-16  9:18 ` Bruce Richardson
2020-10-16  9:27   ` Thomas Monjalon
2020-10-16 12:39 ` [dpdk-dev] [PATCH v2] " Thomas Monjalon
2020-10-16 12:43   ` Bruce Richardson
2020-10-16 15:57     ` Thomas Monjalon

DPDK patches and discussions

Archives are clonable:
	git clone --mirror http://inbox.dpdk.org/dev/0 dev/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 dev dev/ http://inbox.dpdk.org/dev \
		dev@dpdk.org
	public-inbox-index dev


Newsgroup available over NNTP:
	nntp://inbox.dpdk.org/inbox.dpdk.dev


AGPL code for this site: git clone https://public-inbox.org/ public-inbox