Re: [Docutils-users] Insert a section at a specific level in a directive

[David G. <go...@py...>]

On Sun, Jun 14, 2009 at 23:31, Chris Bergstresser<ch...@su...> wrote:
>  Oh, fine.

This could be interpreted as a rather rude way to reply (I'll assume
it's not though). Some care should be taken with email subtlety. :-)

> Top Level Section
> =================
>
> Subsection A
> --------------------
>
> Text in A
>
> .. my_directive:: Subsection B

How will "my_directive" know if Subsection B should be at the same
level as A, or a subsection? What if the order was reversed, and
Subsection B is the first section at its level; should A be at the
same level or lower? Without the section title markup, the parser has
no way of knowing.

Why not just use regular section markup, and use a directive to modify
the doctree however you require? E.g. as prefix:

"""
Subsection A
--------------------

Text in A

.. my_directive::

Subsection B
----------------------
"""

or after the title, working from within the section:

"""
Subsection A
--------------------

Text in A

Subsection B
----------------------

.. my_directive::
"""

I recommend one of these approaches: minimally modify the existing
mechanism (don't reinvent the wheel).

If you insist on doing it the hard way: see the parser
(docutils/parsers/rst/states.py) for how regular section syntax gets
turned into doctree sections, and emulate that process.
RSTState.new_subsection is a good place to start.

-- 
David Goodger <http://python.net/~goodger>