builddoc fails with python 2.7

[KSchopmeyer]

Builddoc fails when building with Python 2.7 with the following information using both the pr #987 and the master branch.

akefile: Creating docs/pywbemlistener/cmdshelp.rst for documentation
PYWBEMTOOLS_TERMWIDTH=120 python -u tools/click_help_capture.py pywbemlistener >docs/pywbemlistener/cmdshelp.rst
Done: Created help command info for cmds: docs/pywbemlistener/cmdshelp.rst
makefile: Creating the documentation as HTML pages
rm -f build_doc/html/index.html
sphinx-build -b html -v -d build_doc/doctrees -c docs -D latex_elements.papersize=a4 docs build_doc/html
Running Sphinx v1.8.5
WARNING: Python 2 is deprecated with sphinx_rtd_theme, update to Python 3
WARNING: Sphinx 1.x is deprecated with sphinx_rtd_theme, update to Sphinx 2.x or greater
WARNING: 'html4_writer' is deprecated with sphinx_rtd_theme
making output directory...
loading intersphinx inventory from https://docs.python.org/2/objects.inv...
loading intersphinx inventory from https://docs.python.org/2/objects.inv...
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://pywbem.readthedocs.io/en/stable/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 17 source files that are out of date
updating environment: 17 added, 0 changed, 0 removed
reading sources... [  5%] appendix

Traceback (most recent call last):
  File "/home/kschopmeyer/virtualenvs/pycli2/local/lib/python2.7/site-packages/sphinx/cmd/build.py", line 304, in build_main
    app.build(args.force_all, filenames)
  File "/home/kschopmeyer/virtualenvs/pycli2/local/lib/python2.7/site-packages/sphinx/application.py", line 341, in build
    self.builder.build_update()
  File "/home/kschopmeyer/virtualenvs/pycli2/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 347, in build_update
    len(to_build))
  File "/home/kschopmeyer/virtualenvs/pycli2/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 360, in build
    updated_docnames = set(self.read())
  File "/home/kschopmeyer/virtualenvs/pycli2/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 468, in read
    self._read_serial(docnames)
  File "/home/kschopmeyer/virtualenvs/pycli2/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 490, in _read_serial
    self.read_doc(docname)
  File "/home/kschopmeyer/virtualenvs/pycli2/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 534, in read_doc
    doctree = read_doc(self.app, self.env, self.env.doc2path(docname))
  File "/home/kschopmeyer/virtualenvs/pycli2/local/lib/python2.7/site-packages/sphinx/io.py", line 318, in read_doc
    pub.publish()
  File "/home/kschopmeyer/virtualenvs/pycli2/local/lib/python2.7/site-packages/docutils/core.py", line 219, in publish
    self.apply_transforms()
  File "/home/kschopmeyer/virtualenvs/pycli2/local/lib/python2.7/site-packages/docutils/core.py", line 200, in apply_transforms
    self.document.transformer.apply_transforms()
  File "/home/kschopmeyer/virtualenvs/pycli2/local/lib/python2.7/site-packages/sphinx/transforms/__init__.py", line 90, in apply_transforms
    Transformer.apply_transforms(self)
  File "/home/kschopmeyer/virtualenvs/pycli2/local/lib/python2.7/site-packages/docutils/transforms/__init__.py", line 171, in apply_transforms
    transform.apply(**kwargs)
  File "/home/kschopmeyer/virtualenvs/pycli2/local/lib/python2.7/site-packages/sphinx/transforms/__init__.py", line 245, in apply
    apply_source_workaround(n)
  File "/home/kschopmeyer/virtualenvs/pycli2/local/lib/python2.7/site-packages/sphinx/util/nodes.py", line 94, in apply_source_workaround
    for classifier in reversed(node.parent.traverse(nodes.classifier)):
TypeError: argument to reversed() must be a sequence

Exception occurred:
  File "/home/kschopmeyer/virtualenvs/pycli2/local/lib/python2.7/site-packages/sphinx/util/nodes.py", line 94, in apply_source_workaround
    for classifier in reversed(node.parent.traverse(nodes.classifier)):
TypeError: argument to reversed() must be a sequence
The full traceback has been saved in /tmp/sphinx-err-cYboG8.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Makefile:547: recipe for target 'build_doc/html/index.html' failed

[KSchopmeyer]

The issue is tied to a sphinx issue sphinx-doc/sphinx#9727 and the conclusion is that the issue is caused by the fact that docutils was recently updated to 0.18 but, while the current version of Sphinx was updated to disallow docutils 0.18, the older version required for use with Python 2.7 (Sphinx 1.8.5 was the last Sphinx that was Python 2.7 compatible) that change was not applied to a version compatible with Python 2.7

[KSchopmeyer]

Note that Sphinx is implementing changes but that they are tied to version 4.3.0 (sphinx-doc/sphinx#9777) but that does nothing for the us and python 2.7. I would bet that it will not be easy to get an update to Sphinx 1.8.5 any more.

Note: the reason we do not fail when testing with more up-to-date versions of Sphinx is that at Sphinx 3.5.4 Sphinx started setting a maximum version on docutils themselves (< 0.18 for Sphinx 4 and < 0.18 for Sphinx 3.5.4). It is the older versions that cause the problem where there was no maximum limit on docutils version.

If we want to be fully protective, we should probably set our minimum sphinx at 3.5.4 rather than 3.0.4

There are proposed workarounds including:

1. Pin docutils to <0.18 in the rtd_requirements.txt and dev-requirements.txt