recommended design style for Sphinx extensions that generate documentation?

[Peter Maydell]

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

[Komiya Takeshi]

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 <peter....@linaro.org>:

> --
> 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 sphinx-users...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/CAFEAcA9gg__vZXKWJuYkPBtskvpvosxjYoWPedvkX-JBj%2Bc9og%40mail.gmail.com.

[Peter Maydell]

On Wednesday, 29 January 2020 17:11:50 UTC, Komiya Takeshi wrote:

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 for the advice.  In the interim before I read your reply

I made some progress with the option-2 (create docutils nodes)

approach, so I might continue with that for the moment, at

least for this specific extension. But I'll bear in mind that

just-write-rST-source is probably the way to go in future.

It occurred to me that in theory Sphinx could have a 'lint'

builder which just syntax-checked the nodes to ensure they

had all the required properties/children/etc. I suspect it

would be a lot of work to try to nail down exactly what the

things it needed to check would be though...

thanks

-- PMM

[Komiya Takeshi]

Indeed, it would be nice if we have lint tool for doctree and indices :-)
It would be very helpful for Sphinx developers too!
Unfortunately I don't have enough time to develop it, but I'd like to
challenge for it if I have time.

2020年1月31日(金) 20:14 Peter Maydell <peter....@linaro.org>:

> --
> 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 sphinx-users...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/03234941-c7f3-4cd0-9a54-b971290be6f4%40googlegroups.com.