1# Copyright (C) Internet Systems Consortium, Inc. ("ISC") 2# 3# SPDX-License-Identifier: MPL-2.0 4# 5# This Source Code Form is subject to the terms of the Mozilla Public 6# License, v. 2.0. If a copy of the MPL was not distributed with this 7# file, you can obtain one at https://mozilla.org/MPL/2.0/. 8# 9# See the COPYRIGHT file distributed with this work for additional 10# information regarding copyright ownership. 11 12# flake8: noqa: E501 13 14import re 15 16from typing import List, Tuple 17 18from docutils import nodes 19from docutils.nodes import Node, system_message 20from docutils.parsers.rst import roles 21 22from sphinx import addnodes 23 24try: 25 from sphinx.util.docutils import ReferenceRole 26except ImportError: 27 # pylint: disable=too-few-public-methods 28 class ReferenceRole(roles.GenericRole): 29 ''' 30 The ReferenceRole class (used as a base class by GitLabRefRole 31 below) is only defined in Sphinx >= 2.0.0. For older Sphinx 32 versions, this stub version of the ReferenceRole class is used 33 instead. 34 ''' 35 def __init__(self): 36 super().__init__('', nodes.strong) 37 38 39GITLAB_BASE_URL = 'https://gitlab.isc.org/isc-projects/bind9/-/' 40 41 42# Custom Sphinx role enabling automatic hyperlinking to GitLab issues/MRs. 43class GitLabRefRole(ReferenceRole): 44 def __init__(self, base_url: str) -> None: 45 self.base_url = base_url 46 super().__init__() 47 48 def run(self) -> Tuple[List[Node], List[system_message]]: 49 gl_identifier = '[GL %s]' % self.target 50 51 target_id = 'index-%s' % self.env.new_serialno('index') 52 entries = [('single', 'GitLab; ' + gl_identifier, target_id, '', None)] 53 54 index = addnodes.index(entries=entries) 55 target = nodes.target('', '', ids=[target_id]) 56 self.inliner.document.note_explicit_target(target) 57 58 try: 59 refuri = self.build_uri() 60 reference = nodes.reference('', '', internal=False, refuri=refuri, 61 classes=['gl']) 62 if self.has_explicit_title: 63 reference += nodes.strong(self.title, self.title) 64 else: 65 reference += nodes.strong(gl_identifier, gl_identifier) 66 except ValueError: 67 error_text = 'invalid GitLab identifier %s' % self.target 68 msg = self.inliner.reporter.error(error_text, line=self.lineno) 69 prb = self.inliner.problematic(self.rawtext, self.rawtext, msg) 70 return [prb], [msg] 71 72 return [index, target, reference], [] 73 74 def build_uri(self): 75 if self.target[0] == '#': 76 return self.base_url + 'issues/%d' % int(self.target[1:]) 77 if self.target[0] == '!': 78 return self.base_url + 'merge_requests/%d' % int(self.target[1:]) 79 raise ValueError 80 81 82def setup(_): 83 roles.register_local_role('gl', GitLabRefRole(GITLAB_BASE_URL)) 84 85# 86# Configuration file for the Sphinx documentation builder. 87# 88# This file only contains a selection of the most common options. For a full 89# list see the documentation: 90# http://www.sphinx-doc.org/en/master/config 91 92# -- Path setup -------------------------------------------------------------- 93 94# If extensions (or modules to document with autodoc) are in another directory, 95# add these directories to sys.path here. If the directory is relative to the 96# documentation root, use os.path.abspath to make it absolute, like shown here. 97# 98# import os 99# import sys 100# sys.path.insert(0, os.path.abspath('.')) 101 102 103# -- Project information ----------------------------------------------------- 104 105project = 'BIND 9' 106# pylint: disable=redefined-builtin 107copyright = '2022, Internet Systems Consortium' 108author = 'Internet Systems Consortium' 109 110version_vars = {} 111with open('../../version', encoding='utf-8') as version_file: 112 for line in version_file: 113 match = re.match(r'(?P<key>[A-Z]+)=(?P<val>.*)', line) 114 if match: 115 version_vars[match.group('key')] = match.group('val') 116 117version = '%s.%s.%s%s%s%s' % ( 118 version_vars['MAJORVER'], 119 version_vars['MINORVER'], 120 version_vars['PATCHVER'], 121 version_vars['RELEASETYPE'], 122 version_vars['RELEASEVER'], 123 version_vars['EXTENSIONS'], 124) 125release = version 126 127# -- General configuration --------------------------------------------------- 128 129# Add any Sphinx extension module names here, as strings. They can be 130# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 131# ones. 132extensions = [] 133 134# Add any paths that contain templates here, relative to this directory. 135templates_path = ['_templates'] 136 137# List of patterns, relative to source directory, that match files and 138# directories to ignore when looking for source files. 139# This pattern also affects html_static_path and html_extra_path. 140exclude_patterns = [ 141 '_build', 142 'Thumbs.db', 143 '.DS_Store', 144 '*.grammar.rst', 145 '*.zoneopts.rst', 146 'build.rst', 147 'catz.rst', 148 'dlz.rst', 149 'dnssec.rst', 150 'dyndb.rst', 151 'logging-categories.rst', 152 'managed-keys.rst', 153 'pkcs11.rst', 154 'platforms.rst', 155 'plugins.rst' 156 ] 157 158# The master toctree document. 159master_doc = 'index' 160 161# -- Options for HTML output ------------------------------------------------- 162 163# The theme to use for HTML and HTML Help pages. See the documentation for 164# a list of builtin themes. 165# 166html_theme = 'sphinx_rtd_theme' 167 168# -- Options for LaTeX output ------------------------------------------------ 169latex_engine = 'xelatex' 170 171# pylint disable=line-too-long 172latex_documents = [ 173 (master_doc, 'Bv9ARM.tex', 'BIND 9 Administrator Reference Manual', author, 'manual'), 174 ] 175 176latex_logo = "isc-logo.pdf" 177