The 'set' datatype in Python does not provide iteration-order
guarantees related to insertion-order. That means that its
usage in the 'split_csv' helper function during documentation
build can produce nondeterministic results.
That is non-desirable for two reasons: it means that the
documentation output may appear to vary unnecessarily between
builds, and secondly there could be loss-of-information in cases
where tag order in the source documentation is significant.
This patch implements order-preserving de-duplication of tags,
allowing authors to specify tags using intentional priority
ordering, while also removing tags that appear more than once.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
