XML template reference¶
XML to RST conversion¶
Restructured Text documents (and fragments of documents) have a tree-like structure that can be approximately described by an element tree. In fact, Sphinx can output XML.
antidox works by converting a XML element tree that is the result of the
transform (we will call this “intermediate XML”) into reST nodes. For most
elements the transformation is straightforward as there is a direct
correspondence. Special cases like directives, localization and indices are
handled via the antidox
XML namespace.
During normal operation, the intermediate XML is never written to a document, but it is kept in memory as an element tree.
Standard Sphinx and reST nodes¶
From the intermediate XML, all unqualified elements are converted to reST nodes
of the same name (docutils.nodes
and sphinx.addnodes
are searched).
If the element does not map to a Text-derived node and there is a TEXT element
inside, a new Text node is created. Otherwise the text is used to create the
node.
Setting attributes¶
Some nodes accept a list of values as arguments. XML element attributes, however, are always string. To work around this issue, antidox allows encoding lists for these attributes by using “|” as a separator.
Additionally, the strings true
and false
are converted to Python’s
bool() and digits are parsed to integers.
Additional information¶
reST nodes are constructed from an argument that is the “raw” source code for
that element, plus a set of keyword arguments. Only nodes derived from Text
can contain text. The rest of the nodes must have a Text-derived node as a
child if the are to have text.
When creating nodes, the template interpreter in antidox sets the “raw” argument to an empty string. Also, all line numbers are set to the line number of the directive, for lack of a more meaningful value.
To apply the XSL transformation, the XML element corresponding to the entity
being documented (e.g. a <compounddef>
or a <memberdef>
) is extracted
from its containing document and the transform is run as if that element was the
root element. This means XPath expressions may give different results when the
the same stylesheet is applied to a whole doxygen XML. In addition, an
<antidox:fakeroot> may be necessary if many top-level elements are to
be generated from a single XML node.
Global stylesheet parameters¶
The XSL following parameters are available at the global scope. Their value is derived from the rst:dir:doxy:c directive options.
XPath extension functions¶
-
antidox:l(node_or_text)
¶ Run the specified text through Sphinx’s locale function. If a node is given, it is transformed into text via
string(.)
.
-
antidox:string-to-ids(node_or_text)
¶ Convert a string into something that is safe to use as a docutils ids field. If a node is given, it is run through
string(.)
. This is useful for automatically generating anchors from section titles.
-
antidox:guess_desctype(refid)
¶ Try to guess the C domain role for the given refid (usually the given as the “id” attribute of a node.) This is usually needed to set the
desctype
andobjtype
indesc
nodes.This function maps to
antidox.doxy.DoxyDB.guess_desctype()
.
-
antidox:refid_to_target(refid)
¶ Generate a target string from a refid. This function maps to
antidox.doxy.DoxyDB.refid_to_target()
.
-
antidox:lower-case(node_or_text)
¶ Convert text to lower-case (similar to the same name function in XPath 2.0.)
-
antidox:upper-case(node_or_text)
¶ Convert text to upper-case (similar to the same name function in XPath 2.0.)
antidox-specific (pseudo)elements¶
<antidox:usercontent>
¶
Placeholder for user-defined content, that is, content given in the body of the rst:dir:doxy:c directive.
If this element is not present, antidox will try to nest the directive body
under a docutils.nodes.desc_content
node. If none is found, it will be
placed as a child of the last top level element.
<antidox:children>
¶
Placeholder for child elements. This node will be replaced by the subtrees of children that result from the children option and no-children option. By default children subtrees are appended to the last root element resulting from the transform.
<antidox:index>
¶
Places cross-reference entries (sphinx.addnodes.index
). Additionally, if
its parent has an ids
attribute, it registers it in the proper domain.
Attributes:
key
- String to be used as
key
for the alphabetical index. It is usually a single letter (the first in the indexed name), but a word can be used too. For more information see the documentation for sphinx.addnodes.indexnode.
<antidox:fakeroot>
¶
As described in Additional information, doxygen XML nodes are extracted to the
top (root) level before applying the XSL template. The result of a XSL tranform
must be a valid XML document which means that, normally, one would only be
able to emit a single (non nested) Sphinx node in a doxy:c
directive.
This node allows circumventing this restriction. After the XSLT step all
<antidox:fakeroot>
are “dissolved”.
Generating roles and directives¶
Directives in reST do not have their own nodes. Rather, they generate nodes that are then inserted in the document. Interpreted text roles such as cross references behave similarly.
<antidox:directive>
¶
This element calls a directive. reST directives are not nodes: they generate nodes that are added to the tree. This element can have the following attributes:
antidox:name
- Name of the directive to invoke (“directive type” in reST terminology.)
- Other parameters
- Other parameters will be intepreted as directive options.
<antidox:directive-argument>
¶
Placed inside <antidox:directive>, its TEXT is translated to arguments for that directive.
<antidox:directive-content>
¶
This element’s TEXT is the content of the containing directive.
<antidox:interpreted>
¶
Inserts an interpreted text role (such as ref
, c:func
,
etc). The contents of the node (which must consist only of text, no child nodes)
is passed as the text argument to the interpreted role.
There is a single attribute, role
, which species the name if the role
(including the domain if necessary.)
Other¶
antidox:compound
¶
Name of the built-in default stylesheet, to be used as href
in xsl:import
and xsl:include
statements, for example
The reason the built-in style is exposed this way and not with a filename is that the file may not exist: for example, this extension may be installed as a zipfile. You can obtain the contents of the built-in stylesheet using the shell.