Context:
This call to nested_parse
adds a Paragraph
node to a Paragraph
node, this look forbidden by the doc, and it also look to misbehave sphinx-side, when translating the document, where we completly loose the nested paragraph once translated.
It renders properly though when not translated.
The linked nested_parse
returns:
<paragraph classes="availability">
<pending_xref refdoc="index" refdomain="std" refexplicit="True" reftarget="availability" reftype="ref" refwarn="True">
<inline classes="xref std std-ref">
Availability
:
Unix, not Emscripten, not WASI.
<paragraph>
Hello world I'm the content of the "availability" directive.
If it's really something that should not be done, maybe some kind of warning at build time could help debugging those issues?
Nesting paragraphs in paragraphs is indeed a violation of the Docutils document model docutils.dtd.
Unfortunately, this is just one example of an "infinite" number of ways you can build invalid documents -- testing for all sorts of violations by custom code may seriously affect performance.
You may consider exporting a test document to XML and test for validity against the docutils.dtd.
Ticket moved from /p/docutils/bugs/466/
However, a transform testing for conformance could be sensible. It may walk over the document tree and for each node check that the parent node is an instance of the well-defined, small set of allowed parent nodes.
Ideas and patches are welcome.
In Docutils 0.22 (since [r9732]), you can validate a Document Tree element (
nodes.Element
instance) and its children by calling itsvalidate()
method.There is also a "transform" that checks a complete document after parsing and reports validation problems as WARNING system messages. It can be activated with the validate configuration setting.
The new "xml" parser validates the parsing result by default, so if you save the source
to a file foo.xml, say, and run
the result is
The original example would also complain about the unknown node
<pending_xref>
as this is an extension by Sphinx.Related
Commit: [r9732]