[Docutils-develop] custom directive that ends current section

[<ma...@he...>]

(Originaly posted on sphinx-dev) Referred to here. 

Hi All. 

I'd like to write a directive which ends the current section, and adds
it own section at the same level.  (directive name = "my_section")

so 

rst =  
""" 

Section 1
=========
[...]

.. my_section

Section 3
=========
[...] 

""" 

should generate 3 sections ; all the same level: 

|
- Section 1
|
- my_section
|
- Section 3
| 

Current state: 
---------------- 

If i 

return [nodes.section(...)] 
in my directive, the result is that "my_section" becomes a section
inside "Section 1": 

|
- Section 1
|    |
|    -  my_section
|
- Section 3

Is there any way to do this? 
A transform afterwards maybe? 

I'm sure someone wants to know why... 

Each section documents a specific business rule. ( mostly human authored
text, end-user friendly,  but also several elements which can be
autogenerated.) 
The my_section aims to automate most of the writing of these sections,
so once the directive is working, each section will be migrated one-by
one to using the "my_section directive". The section title should be
autogerated, so 
the option of doing a directive: my_body   and then: 

Section 1
=========
[...]

Section 2
=========
  .. my_body

Section 3
=========
[...] 

Is not ideal. 

/Martin Helmer