Luckily we don't rely on SphinxDirective functionality which does not
exist in 1.6.7. Replace it with docutils Directive.
transform_content() callback was added only in Sphinx 3.0.0.
Detect if it was not called and call it manually.
The transform_content() function requires access to inner "contentnode"
which is created inside run(). This workaround relies on the order of
node as it was in the pre-3.0.0 versions, but it should not matter as
new versions will not trigger the workaround.
(cherry picked from commit 8796ad7fe8ed24d1287bfd94ef1ee283d778c047)
Ancient versions of docutils cannot cope with bare text inside a table
cell. Wrap text in a paragraph to work around that.
(cherry picked from commit af5bbb433afca3bb600bd409c7421d33c3552aaa)
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)
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 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)
Nested rst syntax is now parsed and rendered. E.g.:
.. namedconf:statement:: example
:short: Use ``this`` **cool** syntax!
(cherry picked from commit 563eb8e1b9)
Introduce a new syntax:
.. namedconf:statementlist::
:filter_tags: acl, resolver
The resulting table contains only items tagged as acl OR resolver.
(cherry picked from commit 33931c97fa)
It turns out it is easier to regenerate Sphinx-mandated structure in
get_objects than to maintain two separate data structures. I should have
realized that before.
(cherry picked from commit 2f2aa1d21c)
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.
(cherry picked from commit 976aef030a)
New and currently unused values can be provided using this syntax:
.. statement:: max-cache-size
:tags: resolver, cache
:short: Short description
The domain stores them in its internal structures for further use.
(cherry picked from commit b12606cebe)
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.
(cherry picked from commit a23fa7edc9)
