diff options
Diffstat (limited to 'doc/arm/conf.py')
| -rw-r--r-- | doc/arm/conf.py | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/doc/arm/conf.py b/doc/arm/conf.py new file mode 100644 index 0000000..6224f0f --- /dev/null +++ b/doc/arm/conf.py @@ -0,0 +1,190 @@ +############################################################################ +# Copyright (C) Internet Systems Consortium, Inc. ("ISC") +# +# SPDX-License-Identifier: MPL-2.0 +# +# This Source Code Form is subject to the terms of the Mozilla Public +# License, v. 2.0. If a copy of the MPL was not distributed with this +# file, you can obtain one at https://mozilla.org/MPL/2.0/. +# +# See the COPYRIGHT file distributed with this work for additional +# information regarding copyright ownership. +############################################################################ + +from pathlib import Path +import re +import sys + +from typing import List, Tuple + +from docutils import nodes +from docutils.nodes import Node, system_message +from docutils.parsers.rst import roles + +from sphinx import addnodes + +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/-/" + + +# Custom Sphinx role enabling automatic hyperlinking to GitLab issues/MRs. +class GitLabRefRole(ReferenceRole): + def __init__(self, base_url: str) -> None: + self.base_url = base_url + super().__init__() + + def run(self) -> Tuple[List[Node], List[system_message]]: + gl_identifier = "[GL %s]" % self.target + + target_id = "index-%s" % self.env.new_serialno("index") + entries = [("single", "GitLab; " + gl_identifier, target_id, "", None)] + + index = addnodes.index(entries=entries) + target = nodes.target("", "", ids=[target_id]) + self.inliner.document.note_explicit_target(target) + + try: + refuri = self.build_uri() + reference = nodes.reference( + "", "", internal=False, refuri=refuri, classes=["gl"] + ) + if self.has_explicit_title: + reference += nodes.strong(self.title, self.title) + else: + reference += nodes.strong(gl_identifier, gl_identifier) + except ValueError: + error_text = "invalid GitLab identifier %s" % self.target + msg = self.inliner.reporter.error(error_text, line=self.lineno) + prb = self.inliner.problematic(self.rawtext, self.rawtext, msg) + return [prb], [msg] + + return [index, target, reference], [] + + def build_uri(self): + if self.target[0] == "#": + return self.base_url + "issues/%d" % int(self.target[1:]) + if self.target[0] == "!": + return self.base_url + "merge_requests/%d" % int(self.target[1:]) + raise ValueError + + +def setup(app): + roles.register_local_role("gl", GitLabRefRole(GITLAB_BASE_URL)) + app.add_crossref_type("iscman", "iscman", "pair: %s; manual page") + + +# +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, make it absolute. +# +sys.path.append(str(Path(__file__).resolve().parent / "_ext")) +sys.path.append(str(Path(__file__).resolve().parent.parent / "misc")) + +# -- Project information ----------------------------------------------------- + +project = "BIND 9" +# pylint: disable=redefined-builtin +copyright = "2023, Internet Systems Consortium" +author = "Internet Systems Consortium" + +m4_vars = {} +with open("../../configure.ac", encoding="utf-8") as configure_ac: + for line in configure_ac: + match = re.match( + r"m4_define\(\[(?P<key>bind_VERSION_[A-Z]+)\], (?P<val>[^)]*)\)dnl", line + ) + if match: + m4_vars[match.group("key")] = match.group("val") + +version = "%s.%s.%s%s" % ( + m4_vars["bind_VERSION_MAJOR"], + m4_vars["bind_VERSION_MINOR"], + m4_vars["bind_VERSION_PATCH"], + m4_vars["bind_VERSION_EXTRA"], +) +release = version + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ["namedconf", "rndcconf"] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "*.inc.rst"] + +# The master toctree document. +master_doc = "index" + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" +html_static_path = ["_static"] +html_css_files = ["custom.css"] + +# -- Options for EPUB output ------------------------------------------------- + +epub_basename = "Bv9ARM" + +# -- Options for LaTeX output ------------------------------------------------ +latex_engine = "xelatex" + +# pylint disable=line-too-long +latex_documents = [ + ( + master_doc, + "Bv9ARM.tex", + "BIND 9 Administrator Reference Manual", + author, + "manual", + ), +] + +latex_logo = "isc-logo.pdf" + +# +# The rst_epilog will be completely overwritten from the Makefile, +# the definition here is provided purely for situations when +# sphinx-build is run by hand. +# +rst_epilog = """ +.. |rndc_conf| replace:: ``/etc/rndc.conf`` +.. |rndc_key| replace:: ``/etc/rndc.key`` +.. |named_conf| replace:: ``/etc/named.conf`` +.. |bind_keys| replace:: ``/etc/bind.keys`` +.. |named_pid| replace:: ``/run/named.pid`` +.. |session_key| replace:: ``/run/session.key`` +""" |