Added debug info for package version issue to Sphinx build

Details:

- The documentation built on RTD from freshly released versions
  shows the previous development version (e.g. e.g. if zhmccli
  0.19.0 has been released, the tip of the master branch is
  tagged with 0.19.0, but RTD 'latest' shows 0.18.1.devNN.
  That version is returned by pkg_resources (pbr just passes
  it on), and the effect can also be seen in local repo clones
  under some conditions (not yet clear exactly when).

  This change shows debug information about the package version
  and git tags when Sphinx builds the documentation (both locally
  and when run on RTD), in order to track down the issue.

  This change also runs 'make builddoc' on every Travis run, so
  that the Sphinx build can be watched there (previously, that
  was run only in the manual CI run to save time in the normal
  Travis runs).

Signed-off-by: Andreas Maier <maiera@de.ibm.com>

.travis.yml

@@ -169,7 +169,7 @@ script:
   - if [[ -n $_MANUAL_CI_RUN ]]; then make pylint; fi
   - make test
   - if [[ -n $_MANUAL_CI_RUN ]]; then make build; fi
-  - if [[ -n $_MANUAL_CI_RUN ]]; then make builddoc; fi
+  - make builddoc
 
 after_success:
   - if [[ "$TRAVIS_OS_NAME" == "linux" && "$TRAVIS_PYTHON_VERSION" == "2.7" && "$PACKAGE_LEVEL" == "latest" && -z $_MANUAL_CI_RUN ]]; then

docs/conf.py

@@ -86,6 +86,24 @@ def package_version(filename, varname):
 vi = VersionInfo('zhmccli')
 version = vi.version_string_with_vcs()
 
+# Debug information to track down the issue with development
+# versions being built when HEAD is tagged with a release.
+print("Debug: conf.py: Debug information for package version issue")
+print("Debug: conf.py: zhmccli version: %s" % version)
+print("Debug: conf.py: Executing: git tag")
+os.system('git tag')
+print("Debug: conf.py: Executing: git log --decorate --oneline |grep 'tag:'")
+os.system('git log --decorate --oneline |grep "tag:"')
+print("Debug: conf.py: Executing: pip list |grep zhmc")
+os.system('pip list |grep zhmc')
+print("Debug: conf.py: Executing: ls -al ../zhmccli.egg-info/")
+os.system('ls -al ../zhmccli.egg-info/')
+print("Debug: conf.py: Executing: cat ../zhmccli.egg-info/PKG-INFO |grep '^Version:'")
+os.system('cat ../zhmccli.egg-info/PKG-INFO |grep "^Version:"')
+print("Debug: conf.py: Executing: cat ../zhmccli.egg-info/pbr.json")
+os.system('cat ../zhmccli.egg-info/pbr.json')
+print("\nDebug: conf.py: End of debug information")
+
 # The full version, including alpha/beta/rc tags.
 release = version