Without this change tables generated by .. namedconf:statementlist::
contained raw text and displayed rst syntax to users.
The raw docutil node returned by rst parser can contain unresolved
references (pending_xref nodes). We just store those nodes and let
Sphinx to resolve them later on.
Beware: This would not work if we injected nodes in later stages of
processing. All unresolved references must be in place before
'doctree-resolved' event is emitted (i.e. before resolve_references() is
called inside Sphinx).
(cherry picked from commit 62f3cf98d3)
This change allows us to generate "unresolved" references and let Sphinx
deal with dereferencing them in later stages. It is not useful by itself
but it serves as preparation for the next commit.
(cherry picked from commit b109c86805)
Formerly resolve_xref() in Sphinx extension called get_objects() from
Sphinx API which subsequently iterated the whole list of objects,
causing single iteration per single reference, which is essentially.
O(n^2). Avoid using get_objects() and access internal dictionary
directly intead.
The docs build time was still dominated by other factors but speedup is
about 10 % on my machine.
(cherry picked from commit 8a5f20121e)
This is super confusing because statement "keys" exists in context
controls and server blocks where it refers to symmetric TSIG key, and it
_also_ exists in dnssec-policy block where it specifies public-private
key pair parameters.
In an (unsuccessful) attempt to disambiguate these two I added bunch of
hyperlinks and a warning.
(cherry picked from commit d88fefbb4a)
Statements ipv4only-contact, ipv4only-enable, ipv4only-server did not
have their own section in the ARM. Now they have.
(cherry picked from commit 1687b40849)
A new syntax
.. namedconf:statementlist::
:filter_blocks: type secondary
allows to generate tables with statements allowed within specified
blocks.
(cherry picked from commit 08a8acffdc)
It would be too easy if we could just call sorted(). Thanks to zone
grammar the most important key "type" gets sorted near end, so we pull
it up to the top using a hack.
(cherry picked from commit 5c04e3c524)
It turns out the tree of dictionaries is not the best structure to
represent our grammar, unfortunatelly. The problem is that "zone" has
several context-dependent variants which change meaning of "zone" based
on inner field "type".
Redesigning the whole structure does not seem to be worth, so I settled
on this terrible hack.
(cherry picked from commit 0392144e99)
A new flag
.. namedconf:statement::
:suppress_grammar:
suppresses pretty-printing grammar.
It is useful mostly for zones because each zone has it's own grammar, so
printing all of them at once usually does not make sense.
(cherry picked from commit 1f5bc4fe3b)
A helper is needed to combine cfg_test output for generic options and
all the type-dependent zone block variants.
(cherry picked from commit a691ebd0c9)
It produces the same format as cfg_test --grammar. The advantage is that
it allows to print any node in configuration the tree, not just whole
blocks.
(cherry picked from commit 190004e46c)
The utility detects statements which use the same name (e.g.
max-zone-ttl) but use different grammar in different contexts. These
typically need special case in docs.
(cherry picked from commit 8960d51aa3)
It transforms named.conf/rndc.conf grammar from text format into Python
dictionary. This allows granular access to grammar elements.
Beware: It heavity depens on cfg_test output format!
(cherry picked from commit df08982930)
It uses the same mechanism as all other grammars, but the file is named
differently to distinguish it from named.conf grammars.
(cherry picked from commit fb474de3ab)
The next commit is going to add parser for ISC configuration format.
To simplify the parser the grammar files in doc/misc are no longer
line-wrapped as handling it would make the grammar parser unnecessairly
complicated.
This affects visible output in the ARM, but in the end we are going to
replace the auto-generated .rst files with grammar pretty printed, so
formatting of these files does not matter in practical terms.
(cherry picked from commit 699570cdec)
Nested rst syntax is now parsed and rendered. E.g.:
.. namedconf:statement:: example
:short: Use ``this`` **cool** syntax!
(cherry picked from commit 563eb8e1b9)
Unfortunatelly logging and zone blocks use file statements with
different semantics but the same name.
There is no sane way to disambiguate them in text, so let's remove the
link anchor from logging so we can link to the file statement in zone.
My assumption is that linking to logging { file } is very unlikely
because logging is self-contained in one block but zone config is all
over the place.
(cherry picked from commit fbcaa44851)
Unfortunatelly dnssec-policy and servers blocks use keys statements with
a totally different grammar and semantics but the same name.
There is no sane way to disambiguate them in text, so let's remove the
link anchors to prevent errorneous linking.
(cherry picked from commit d6b2423c99)
control { inet ... allow keys read-only }; are not actual statements
but in fact arguments of a statement. Remove .. namedconf:statement::
syntax to avoid collisions with other statements of the same name.
(cherry picked from commit caf2675ef8)
