Enable building documentation with Sphinx < 2.0.0

The ReferenceRole class is only available in Sphinx >= 2.0.0, which
makes building BIND 9 documentation impossible with older Sphinx
versions:

    Running Sphinx v1.7.6

    Configuration error:
    There is a programable error in your configuration file:

    Traceback (most recent call last):
      File "/usr/lib/python3.6/site-packages/sphinx/config.py", line 161, in __init__
        execfile_(filename, config)
      File "/usr/lib/python3.6/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
        exec_(code, _globals)
      File "conf.py", line 21, in <module>
        from sphinx.util.docutils import ReferenceRole
    ImportError: cannot import name 'ReferenceRole'

Work around the problem by defining a stub version of the ReferenceRole
class if the latter cannot be imported.  This allows documentation
(without GitLab hyperlinks in release notes) to be built with older
Sphinx versions.

(cherry picked from commit 8f8bbae3fc2fb82fc45d0a5e406182e8c28571e2)

diff --git a/doc/arm/conf.py b/doc/arm/conf.py
index a7daf5ea09351d742df211157677297eee19d175..0503f1eb6abac88105c5239449b1e11bbd24b1a2 100644 (file)
--- a/doc/arm/conf.py
+++ b/doc/arm/conf.py
@@ -18,7 +18,20 @@ from docutils.nodes import Node, system_message
 from docutils.parsers.rst import roles
 
 from sphinx import addnodes
-from sphinx.util.docutils import ReferenceRole
+
+try:
+    from sphinx.util.docutils import ReferenceRole
+except ImportError:
+    # pylint: disable=too-few-public-methods
+    class ReferenceRole(roles.GenericRole):
+        '''
+        The ReferenceRole class (used as a base class by GitLabRefRole
+        below) is only defined in Sphinx >= 2.0.0.  For older Sphinx
+        versions, this stub version of the ReferenceRole class is used
+        instead.
+        '''
+        def __init__(self):
+            super().__init__('', nodes.strong)
 
 
 GITLAB_BASE_URL = 'https://gitlab.isc.org/isc-projects/bind9/-/'