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