mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-08-22 10:10:06 +00:00
Code Issues Releases Wiki Activity
bind/doc/arm/_ext/namedconf.py

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

37 lines
1.0 KiB
Python
Raw Normal View History

Add Sphinx extension to help with ARM maintenance and cross-linking The extension provides a "Sphinx domain factory". Each new Sphinx domain defines a namespace for configuration statements so named.conf and rndc.conf do not clash. Currently the Sphinx domains are instantiated twice and resuling domains are named "namedconf" and "rndcconf". This commit adds a single new directive: .. statement:: max-cache-size It is namespaced like this: .. namedconf:statement:: max-cache-size This directive generates a new anchor for configuration statement and it can be referenced like :any:`max-cache-size` (if the identifier is unique), or more specific :namedconf:ref:`max-cache-size`. It is based on Sphinx "tutorial" extension "recipe". Beware, some details in Sphinx docs are not up-to-date, it's better to read Sphinx and docutil sources.
2022-05-10 15:00:06 +02:00
############################################################################
# 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.
############################################################################
"""
Sphinx domain "namedconf". See iscconf.py for details.
"""
replace the build system with meson Meson is a modern build system that has seen a rise in adoption and some version of it is available in almost every platform supported. Compared to automake, meson has the following advantages: * Meson provides a significant boost to the build and configuration time by better exploiting parallelism. * Meson is subjectively considered to be better in readability. These merits alone justify experimenting with meson as a way of improving development time and ergonomics. However, there are some compromises to ensure the transition goes relatively smooth: * The system tests currently rely on various files within the source directory. Changing this requirement is a non-trivial task that can't be currently justified. Currently the last compiled build directory writes into the source tree which is in turn used by pytest. * The minimum version supported has been fixed at 0.61. Increasing this value will require choosing a baseline of distributions that can package with meson. On the contrary, there will likely be an attempt to decrease this value to ensure almost universal support for building BIND 9 with meson.
2024-04-16 15:13:53 +03:00
Add table generator into Sphinx config extension New directive .. statementlist:: generates table of statements in a the given domain (named.conf or rndc.conf). The table contains link to definition, short description, and also list of tags. Short description and tags have to be provided by user using optional parameters. E.g.: .. statement:: max-cache-size :tags: resolver, cache :short: Short description .. statementlist:: is currently not parametrized. This modification is based on Sphinx "tutorial" extension "TODO". The main trick is to use placeholder node for .. statementlist:: and replace it with table at later stage, when all source files were processed and all cross-references can be resolved. Beware, some details in Sphinx docs are not up-to-date, it's better to read Sphinx and docutil sources.
2022-05-10 14:50:34 +02:00
from docutils import nodes
Add Sphinx extension to help with ARM maintenance and cross-linking The extension provides a "Sphinx domain factory". Each new Sphinx domain defines a namespace for configuration statements so named.conf and rndc.conf do not clash. Currently the Sphinx domains are instantiated twice and resuling domains are named "namedconf" and "rndcconf". This commit adds a single new directive: .. statement:: max-cache-size It is namespaced like this: .. namedconf:statement:: max-cache-size This directive generates a new anchor for configuration statement and it can be referenced like :any:`max-cache-size` (if the identifier is unique), or more specific :namedconf:ref:`max-cache-size`. It is based on Sphinx "tutorial" extension "recipe". Beware, some details in Sphinx docs are not up-to-date, it's better to read Sphinx and docutil sources.
2022-05-10 15:00:06 +02:00
import iscconf
Give Sphinx configuration domains access to grammar
2022-05-11 10:38:05 +02:00
import mergegrammar
Add Sphinx extension to help with ARM maintenance and cross-linking The extension provides a "Sphinx domain factory". Each new Sphinx domain defines a namespace for configuration statements so named.conf and rndc.conf do not clash. Currently the Sphinx domains are instantiated twice and resuling domains are named "namedconf" and "rndcconf". This commit adds a single new directive: .. statement:: max-cache-size It is namespaced like this: .. namedconf:statement:: max-cache-size This directive generates a new anchor for configuration statement and it can be referenced like :any:`max-cache-size` (if the identifier is unique), or more specific :namedconf:ref:`max-cache-size`. It is based on Sphinx "tutorial" extension "recipe". Beware, some details in Sphinx docs are not up-to-date, it's better to read Sphinx and docutil sources.
2022-05-10 15:00:06 +02:00
Add table generator into Sphinx config extension New directive .. statementlist:: generates table of statements in a the given domain (named.conf or rndc.conf). The table contains link to definition, short description, and also list of tags. Short description and tags have to be provided by user using optional parameters. E.g.: .. statement:: max-cache-size :tags: resolver, cache :short: Short description .. statementlist:: is currently not parametrized. This modification is based on Sphinx "tutorial" extension "TODO". The main trick is to use placeholder node for .. statementlist:: and replace it with table at later stage, when all source files were processed and all cross-references can be resolved. Beware, some details in Sphinx docs are not up-to-date, it's better to read Sphinx and docutil sources.
2022-05-10 14:50:34 +02:00
class ToBeReplacedStatementList(nodes.General, nodes.Element):
"""
Placeholder, does nothing, but must be picklable
(= cannot be in generated class).
"""
Add Sphinx extension to help with ARM maintenance and cross-linking The extension provides a "Sphinx domain factory". Each new Sphinx domain defines a namespace for configuration statements so named.conf and rndc.conf do not clash. Currently the Sphinx domains are instantiated twice and resuling domains are named "namedconf" and "rndcconf". This commit adds a single new directive: .. statement:: max-cache-size It is namespaced like this: .. namedconf:statement:: max-cache-size This directive generates a new anchor for configuration statement and it can be referenced like :any:`max-cache-size` (if the identifier is unique), or more specific :namedconf:ref:`max-cache-size`. It is based on Sphinx "tutorial" extension "recipe". Beware, some details in Sphinx docs are not up-to-date, it's better to read Sphinx and docutil sources.
2022-05-10 15:00:06 +02:00
def setup(app):
Give Sphinx configuration domains access to grammar
2022-05-11 10:38:05 +02:00
grammar = mergegrammar.combine()
return iscconf.setup(
app, "namedconf", "named.conf", ToBeReplacedStatementList, grammar
)
Reference in New Issue Copy Permalink