sphinx: report errors when dependencies are not met

Submitted by Nicolas Dechesne on Sept. 18, 2020, 9:09 a.m. | Patch ID: 176622

Details

Message ID 20200918090953.555516-1-nicolas.dechesne@linaro.org
State New
Headers show

Commit Message

Nicolas Dechesne Sept. 18, 2020, 9:09 a.m.
To build the Sphinx documentation, we have the following dependencies:
* sphinx
* sphinx_rtd_theme
* pyyaml

If any of these dependencies are missing, we might end up with some
cryptic error messages. This patch adds better error reporting when
dependencies are not met.

Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
---
 documentation/Makefile.sphinx      |  4 ++++
 documentation/conf.py              | 14 ++++++++++----
 documentation/sphinx/yocto-vars.py | 11 ++++++++++-
 3 files changed, 24 insertions(+), 5 deletions(-)

Patch hide | download patch | download mbox

diff --git a/documentation/Makefile.sphinx b/documentation/Makefile.sphinx
index c663c2954..c9518558b 100644
--- a/documentation/Makefile.sphinx
+++ b/documentation/Makefile.sphinx
@@ -9,6 +9,10 @@  SOURCEDIR     = .
 BUILDDIR      = _build
 DESTDIR       = final
 
+ifeq ($(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi),0)
+$(error "The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed")
+endif
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/documentation/conf.py b/documentation/conf.py
index 34d1bc97a..f2dd2556f 100644
--- a/documentation/conf.py
+++ b/documentation/conf.py
@@ -91,10 +91,16 @@  intersphinx_mapping = {
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
-html_theme_options = {
-    'sticky_navigation': False,
-}
+try:
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_options = {
+        'sticky_navigation': False,
+    }
+except ImportError:
+    sys.stderr.write("The Sphinx sphinx_rtd_theme HTML theme was not found.\
+    \nPlease make sure to install the sphinx_rtd_theme python package.\n")
+    sys.exit(1)
 
 html_logo = 'sphinx-static/YoctoProject_Logo_RGB.jpg'
 
diff --git a/documentation/sphinx/yocto-vars.py b/documentation/sphinx/yocto-vars.py
index 568947299..8083d7da1 100644
--- a/documentation/sphinx/yocto-vars.py
+++ b/documentation/sphinx/yocto-vars.py
@@ -1,10 +1,19 @@ 
 #!/usr/bin/env python
 import re
-import yaml
+import sys
 
 import sphinx
 from sphinx.application import Sphinx
 
+# This extension uses pyyaml, report an explicit
+# error message if it's not installed
+try:
+    import yaml
+except ImportError:
+    sys.stderr.write("The Yocto Project Sphinx documentation requires PyYAML.\
+    \nPlease make sure to install pyyaml python package.\n")
+    sys.exit(1)
+
 __version__  = '1.0'
 
 # Variables substitutions. Uses {VAR} subst using variables defined in poky.yaml