From 8f8bbae3fc2fb82fc45d0a5e406182e8c28571e2 Mon Sep 17 00:00:00 2001 From: Petr Mensik Date: Fri, 15 Oct 2021 22:07:53 +0200 Subject: [PATCH] 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 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. --- doc/arm/conf.py | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/doc/arm/conf.py b/doc/arm/conf.py index b8aca9b33c..704c96c5d8 100644 --- 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/-/'