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