From: Thomas Monjalon <thomas@monjalon.net>
To: dev@dpdk.org
Cc: david.marchand@redhat.com, bruce.richardson@intel.com
Subject: [dpdk-dev] [PATCH] doc: make sphinx errors more visible
Date: Fri, 16 Oct 2020 05:39:55 +0200 [thread overview]
Message-ID: <20201016033955.2566518-1-thomas@monjalon.net> (raw)
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
next reply other threads:[~2020-10-16 3:40 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-10-16 3:39 Thomas Monjalon [this message]
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20201016033955.2566518-1-thomas@monjalon.net \
--to=thomas@monjalon.net \
--cc=bruce.richardson@intel.com \
--cc=david.marchand@redhat.com \
--cc=dev@dpdk.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).