Hi; I had a design question about what the recommended/expected
design is for Sphinx extensions which have directives that generate
documentation. There seem to be two possible approaches:
(1) in the python code, create the documentation as rST source text,
and then use a ViewList and sphinx.util.nodes.nested_parse_with_titles()
to parse that into docutils nodes to return. In this style, if you
for instance wanted to output a section heading you'd make the generated
rST to be parsed include 'heading\n-------', and so on.
(2) in the python code, directly assemble a tree of docutils nodes.
IN this style, if you want a section heading you call nodes.section()
to create a section, nodes.title() to create the title node, and then
add the title node to the section node, and so on.
Is one of these two approaches preferred to the other?
I've been experimenting with writing some simple Sphinx extensions,
and although it seems like approach 2 ought to be a neater way
to do things (for instance you don't need to manually track how
indented the rST text you're generating has to be), I keep running
into undocumented pitfalls. For instance, when you call
nodes.section() to create a section node, you must pass it an
argument to set an id to a serial number, like this:
section_id = 'myext-%d' % env.new_serialno('myext')
current_node = nodes.section(ids=[section_id])
as otherwise Sphinx will throw an exception when it later tries
to output the document. Similarly, if you create a description
node with sphinx.addnodes.desc() then Sphinx will crash in the
HTML writer if the node doesn't have an 'objtype' attribute.
I couldn't find where these requirements are documented -- am
I looking in the wrong place in the docs? Or are these requirements
not documented because this sort of assembly of a document
out of a tree of nodes is not something that extensions are
really expected to be doing (ie I should design my extension
in some other way) ?
thanks
-- PMM
--
You received this message because you are subscribed to the Google Groups
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/sphinx-users/CAFEAcA9gg__vZXKWJuYkPBtskvpvosxjYoWPedvkX-JBj%2Bc9og%40mail.gmail.com.
