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