[Docutils-users] Question About Section Levels

[Kent B. <ken...@bo...>]

As I understand it reStructuredText section levels are absolute, not
relative. That is, at any point one can do another section at the
current level, do a section one level deeper, or do a section
shallower. But in each case it must be an explicit level indicated
by an explicit underlining character.

Is there a way to do a section that is merely "this level" or "one
deeper than the current level" or "X number of levels shallower than
the current level"? That's all reStructuredText wants to know, there
must be a way to say that...

The use-case is to make include files useful at different
levels. Imagine a long document with lots of detail sitting in
different include files, and imagine an executive summary document
that has less detail, but wants to include a specific section to
highlight something notable, using an include file that is also used
by the long document. Cool, no problem...but what if the section
level in the executive summary will be shallower than in the
detailed document?

Is there some option to include that will make contents relative to
the depth at which the include directive appeared?

Is there some way I might make a custom directive that can do
relative sections?

Thanks,

-kb