Hi Peter, I think both approach is okay. But, as you experienced, second approach requires you a knowledge of target document tree. And, it is not documented well unfortunately. I've usually read source code of directives, roles, Sphinx itself and other components to know its structure of doctrees. I feel toughness is needed to do that. So I recommend first approach to you if possible.
Thanks, Takeshi KOMIYA 2020年1月28日(火) 2:20 Peter Maydell <[email protected]>: > > 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. -- 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/CAFmkQAM9ZMLTfsEzOfqQOkOh2zYygUFoJU1W6HxrYW4svQmk0g%40mail.gmail.com.
