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

32 lines
946 B
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 "rndcconf". See iscconf.py for details.
"""
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
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 a 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):
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
return iscconf.setup(app, "rndcconf", "rndc.conf", ToBeReplacedStatementList)
Reference in New Issue Copy Permalink