Re: [Docutils-users] closing a header block

[Sidney C. <si...@ji...>]

Hi Guenter,

This is not only impossible (with standard rST syntax), it is also an
> invalid Doctils document tree.
> https://docutils.sourceforge.io/docs/ref/docutils.dtd
> https://docutils.sourceforge.io/docs/ref/doctree.html#element-hierarchy


Ok, that settles it. The restriction seems strange and somewhat arbitrary
to my programmer's eye, but it is there alright.

A similar request was filed to the issue tracker.
> https://sourceforge.net/p/docutils/feature-requests/74
> It turned out to be about an intermediate structure (adding sections by a
> directive). In this case, the resulting doctree would be valid but telling
> the section-adding-directive where to add these sections seems a better
> solution than changing rST syntax or adding a section-closing directive in
> Docutils.
>

Yes, that seems very much related to what I was thinking about.

As it turns out handling this stuff fully at the sphinx level has its own
set of challenges. Especially the toctree stuff and how it interacts with
the section headers seems quite badly designed I am sorry to say, to the
point that the general recommendation seems to be: don't use them in the
same document -- which is annoying (and hard to defend from a usability
perspective). I had hoped that some alternative solution with help from the
docutils level could be useful; but I guess this will need to be fully
fixed at the sphinx level after all.

Thanks,
  Sidney