restructuredtext filter does not return the correct content

[Julian]

I'm using the django.contrib.flatpages with restructuredtext markup. I've tested it with a small

Disclaimer
==========

This is a *test*.

After all, the disclaimer part is not rendered. This happens because the renderer returns a parts and its fragment key is used. The ​docutils doc reads that the fragment does not contain the document title. I've added a patch which makes use of the html_body key.

[Julian]

working on a proper patch.

[Julian]

check.

[Daniel F Moisset]

triaging

[Daniel F Moisset]

The patch looks ok. The generated output adds a <div> element around the content but I think that's reasonable

[Russell Keith-Magee]

Adding a diff where one didn't exist previously is a pretty big backwards incompatibility. I'm not sure what the right way forward is here, but the existing test cases must pass without modification.

Three suggestions:

• Automated inspection of the document contents; if it contains parts that aren't rendered as part of fragment, *then* include the div.
• An argument that turns on 'full document' insertion
• A second template filter. I'd rather not go down this path; I'm really only mentioning it for completeness.

[Julien Phalip]

You can invert this default docutils behaviour using this setting:

RESTRUCTUREDTEXT_FILTER_SETTINGS = {
    'doctitle_xform': False,
}

RESTRUCTUREDTEXT_FILTER_SETTINGS is already mentioned in the contrib.markup doc, but this seems like a frequent enough use case to add a note about this particular setting. So what we need here is a documentation patch.

[Robin]

Replying to julien

I find that doctitle_xform:false will cause problem with section numbering.
Consider the following:

.. section-numbering::

Title
=====

Sub Title
---------

Sub Title
---------

if doctitle_xform is true and if django.contrib.markup.templatetags.markup.restructuredtext returns parts fragment, the rst code will produce:

1 Sub Title

2 Sub Title

if doctitle_xform is false and if django.contrib.markup.templatetags.markup.restructuredtext returns parts fragment, the rst code will produce:

1 Title

1.1 Sub Title

1.2 Sub Title

None of the result above is exactly right. I personally think the correct result should be:

Title

1 Sub Title

2 Sub Title

But how do I achieve that without writing my own restructuredtext function?

[Tim Graham]

There are plans to deprecate contrib.markup (#18054) so marking this as won't fix.