Code

Opened 4 years ago

Closed 20 months ago

#14449 closed Cleanup/optimization (wontfix)

restructuredtext filter does not return the correct content

Reported by: feuervogel Owned by: nobody
Component: Documentation Version: 1.3
Severity: Normal Keywords: markup, restructuredtext
Cc: robinchew@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: no UI/UX: no

Description

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.

Attachments (1)

markup-rest.diff (2.7 KB) - added by feuervogel 4 years ago.

Download all attachments as: .zip

Change History (11)

comment:1 Changed 4 years ago by feuervogel

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

working on a proper patch.

Changed 4 years ago by feuervogel

comment:2 Changed 4 years ago by feuervogel

check.

comment:3 Changed 3 years ago by dmoisset

  • Owner changed from nobody to dmoisset

triaging

comment:4 Changed 3 years ago by dmoisset

  • Owner changed from dmoisset to nobody
  • Triage Stage changed from Unreviewed to Ready for checkin

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

comment:5 Changed 3 years ago by russellm

  • Patch needs improvement set
  • Triage Stage changed from Ready for checkin to Accepted

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.

comment:6 Changed 3 years ago by gabrielhurley

  • Component changed from Contrib apps to contrib.contenttypes

comment:7 Changed 3 years ago by julien

  • Component changed from contrib.contenttypes to Documentation
  • Easy pickings unset
  • Severity set to Normal
  • Type set to Cleanup/optimization

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.

comment:8 Changed 3 years ago by robin

  • Cc robinchew@… added
  • UI/UX unset

comment:9 Changed 2 years ago by robin

  • Version changed from 1.2 to 1.3

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?

comment:10 Changed 20 months ago by timo

  • Resolution set to wontfix
  • Status changed from new to closed

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

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.