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.

diff --git a/doc/arm/conf.py b/doc/arm/conf.py
index b8aca9b33c92b9a8541d122a28148d5a4927f2ed..704c96c5d8ace3d5b92caa59f910defb16be05c2 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/-/'