Option to have headers behave more like `include`

[mathiasertl]

Add the header_update_levels option to let templates behave like the include directive when it comes to headers. This makes it easier to include whole chapters in similar documents via templates, similar to what the include directive is often used for.

Assume you have this file that we use as include or template:

****************
Stars in include
****************

Some text.

and using this source document:

###########
First-level
###########

****************
Second in source
****************

some text

.. include:: test.rst

.. jinja:: first_ctx
   :file: test.rst

.. jinja:: first_ctx
   :file: test.rst
   :header_update_levels:

... the header included via include will show at the same level as Second in source. In the first jinja template directive, the header (and all other headers) will be in the levels below the active level of the caller, so a level three header in this case. The header in the second jinja template directive will behave the same way as the include directive.

See also the docstring for nested_parse_with_titles, which states the function is useful for "when the parsed content comes from a completely different context, such as docstrings." The behavior for the option I have adapted here is from the original include directive (yes, docutils appears to be actually using SVN).

PS: I couldn't think of the perfect option name yet -.-. If you have a better suggestion...

[tardyp]

the feature looks great, but I would prefer if you add a test for it. I also have to make sure the CI runs on PR... your last PR actually did brake the CI :)

[mathiasertl]

I also have to make sure the CI runs on PR...

Yes I was wondering about that because...

your last PR actually did brake the CI :)

:-).

[mathiasertl]

your last PR actually did brake the CI :)

https://github.com/mathiasertl/django-ca/blob/master/.github/workflows/tests.yml#L2-L5

Here's what I use. Once you have that (or similar) in, I'll of course push a fix for the tests for my last PR as well.

[tardyp]

cool. tests passes. but we need new tests for this new feature. :)

[mathiasertl]

but we need new tests for this new feature.

I completely agree. on it.

[mathiasertl]

Here you go with some nice test cases ;-)

[tardyp]

cool tests! I'd appreciate a squash of those messy commits and we're good to go! ;)

[mathiasertl]

force-pushed this into one. (edit: update missing file)

[tardyp]

thanks a bunch!