A docutils document is based on a hierarchy of nodes. They say throughout that the nodes are XML (or at least XML-like) and there are ways to dump documents and document fragments in XML format. They even produce a DTD describing an XML document format for nodes.
I want to generate docutils nodes using a non-Python tool, serialize them into a machine-readable format, then load them with docutils (as part of a Sphinx plugin).
I tried to find a way to load either a full XML document or an XML fragment (in the DTD-specified format) and get back a node tree, but I can't find anything. Is there any way to read the docutils XML format back into nodes, that is, the reverse of Node.asdom()
?
More generally, is there any machine-readable format that I can load with docutils that describes a node tree? Either something based on XML or some other format?
The Docutils repository version 0.22b.dev introduces a "Docutils XML" parser that can parse an XML serialisation back into a Document Tree.
So you may try it with, e.g.,
rst2xml my_document.rst > my_document.xml
# edit my_document.xml
docutils --parser=xml --writer=html5 my_document.xml > my_document.html
But it should also work with XML input generated by other means (or hand-crafted), as long as it is valid.
You may also include a complete or partial document in a rST source employing the parser
"include" directive option like
.. include:: my_document.xml
:parser: xml
Caveat: As a Docutils module, the parser may/will fail on extensions to the Document Tree elements added by Sphinx.