doc: add tool for verifying installed doc tools

Added a python script that displays versions of doc building tools
(e.g., doxygen, breathe, sphinx) to help verify doc building environment
is properly set up (can help doc building problem diagnostic, as shown
in issue #1333

Update doc build documentation to reference this script.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

Author: dbkinder

doc/scripts/requirements.txt

@@ -1,5 +1,5 @@
 breathe==4.9.1
-sphinx==1.7.5
+sphinx==1.7.7
 docutils==0.14
-sphinx_rtd_theme
+sphinx_rtd_theme==0.4.0
 kconfiglib

doc/scripts/show-versions.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+#
+# Copyright (c) 2018, Intel Corporation
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# Show installed versions of doc building tools
+
+import subprocess
+
+print ("breathe          version: " +
+          __import__("breathe").__version__ + "\n" +
+       "docutils         version: " +
+          __import__("docutils").__version__ + "\n" +
+       "sphinx           version: " +
+          __import__("sphinx").__version__ + "\n" +
+       "sphinx_rtd_theme version: " +
+          __import__("sphinx_rtd_theme").__version__ + "\n" +
+       "doxygen          version: " +
+          subprocess.check_output(["doxygen", "-v"]).decode("utf-8"))

doc/tutorials/docbuild.rst

@@ -130,7 +130,7 @@ Our documentation processing has been tested to run with:
 
 * Python 3.6.3
 * Doxygen version 1.8.13
-* Sphinx version 1.7.5
+* Sphinx version 1.7.7
 * Breathe version 4.9.1
 * docutils version 0.14
 * sphinx_rtd_theme version 0.4.0
@@ -160,6 +160,13 @@ tools:
 
 And with that you're ready to generate the documentation.
 
+.. note::
+
+   We've provided a script you can run to show what versions of the
+   doc building tools you have installed ::
+
+      doc/scripts/show-versions.py
+
 Documentation presentation theme
 ********************************