custom directive: start new section

[Martin Helmer]

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
|



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?



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.

[Komiya Takeshi]

Hi,

I guess it is restriction of directives and we can't do that. But I
don't know that in detail.
Please ask it to docutils mailing list.

Thanks,
Takeshi KOMIYA

Post by Martin Helmer
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
=========
[...]
"""
|
- Section 1
|
- my_section
|
- Section 3
|
If i
return [nodes.section(...)]
in my directive, the result is that "my_section" becomes a section inside
|
- Section 1
| |
| - my_section
|
- Section 3
Is there any way to do this?
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.
--
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an
For more options, visit https://groups.google.com/d/optout.

[Rob van der Valk]

Hi Martin,

I would think along the following line:

- within your current level the sequence will be that within section one
you add something, if you let it go its normal course. This may be a node
without actual content, which is easily made and returned, if necessary at
all: returning none might be just fine.

- section 1 is actually called/linked one level up, in 'children' of some
higher section. What you actually want is to append your section on that
level. I think you can just actually do that.

- I would have to look how to get there: something with self.state.document.settings.env,
from your directive. Not sure though, I would have to look thru stuff
myself to find precise location. I use
a combo of dir statements on the different levels to figure out what the
actual structure is, but reading docutils might be simpler.

- My guess would actually also be that a new section would by necessity be
observed by the previous section parser first, and that a flag is used to
denote that the section is ended. No idea whether this is correct, but if
so that might be easy to locate in the docutils code.

- Still: adding a section would bring up questions like: is your question
implied to be on same level (par, sub-par etc) as section1? Is the
numbering working fine? (Should be, I would certainly hope par numbering
happens after reading, maybe even as late as the writer.).

I would start with looking at the structure given by self.state.document.settings.env,
or better, the root of the doctree (must be somewhere, not?). By sheer
observation you should be able to find the section, maybe get pointers from
that...

Good hunting!
Rob

Post by Martin Helmer
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
=========
[...]
"""
|
- Section 1
|
- my_section
|
- Section 3
|
If i
return [nodes.section(...)]
in my directive, the result is that "my_section" becomes a section inside
|
- Section 1
| |
| - my_section
|
- Section 3
Is there any way to do this?
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]

Ok, after reading the state_machine code, I got a hunch, tried it out, and
it seems to work.

A simple " raise EOFError" in the directive will terminate the current
section. This is how the parser does it then it encounters a section header
which can't be a subheader of the current level.

A clean implementation would be to implement a directive ".. end_section"
which does a "raise EOFError" and nothing else.
Then my document would look like:


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


.. end_section

.. my_section


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


Which is acceptable I guess...

However I went a step further and implemented a "double-visit" of the
"my_section" directive:

RAISE_EOF = True


class MyDirective(Directive):
def run(self):
global RAISE_EOF
[...]
if RAISE_EOF:
RAISE_EOF = False
self.state_machine.goto_line(self.lineno-2) # apparently -2 is
the magic number...
raise EOFError

RAISE_EOF = True

[...]


So far, no adverse side effects...