Opened 10 years ago

Closed 8 years ago

#3308 closed defect (worksforme)

Escaped documentation in admin site

Reported by: Noah Slater <nslater@…> Owned by: nobody
Component: contrib.admin Version:
Severity: normal Keywords:
Cc: nslater@… Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

The automatically generated documentation escapes the HTML markup provided by docutils.

A docstring on a view such as this:

def foo(request):
    """bar"""
    return None

... will generate a documentation "summary" (title) of:

<p>bar</p>

... or literally (the characters sent over the wire):

<h2 class="subhead">&lt;p&gt;bar&lt;/p&gt;
</h2>

I have been digging through the code and cannot find a clean way to get around this short of writing my own templates.

I do think I should have to write my own templates to work around a (presumed) bug.

Change History (8)

comment:1 Changed 10 years ago by Noah Slater <nslater@…>

Edit: "I do not think I should have to write my own templates..."

comment:2 Changed 10 years ago by Chris Beaven

Triage Stage: UnreviewedDesign decision needed

Can someone confirm current action isn't what we want and then forward triage stage to Accepted.

comment:3 Changed 10 years ago by Malcolm Tredinnick

Triage Stage: Design decision neededAccepted

Well, the above example looks wrong, but a fix is going to need careful thought: any raw text should be escaped before being dumped into the doc pages, just so that you can write "3 < 5" in your docstrings and not have it break on output. Anything that has gone through docutils, though, should not be escaped, since it's already HTML. I used to remember which parts were which, but I do remember it's not too hard to work out.

However, the bug also shows another problem: the "bar" string really doesn't want to be in paragraph tags in the first place. So we may need to look at that as well. May be multiple problems here, or all handled by one simple fix. Not sure.

comment:4 Changed 8 years ago by Luke Plant

Relates to #2411 which has an out of date patch. I don't seem to be able to reproduce this though - the 'summary' <h2> title never appears in my admin/doc/views/ page.

comment:5 Changed 8 years ago by CaptainCapacitor

I think it might be prudent to look into applying Wiki formatting for the docstrings. It's less intrusive than HTML and can still be easily read from a command line.

comment:6 Changed 8 years ago by Raphaël Braud

Resolution: fixed
Status: newclosed

Since r6671, it's working : docstring are passed to parse_rst which marks safe the string.

Closing ticket...

comment:7 Changed 8 years ago by Raphaël Braud

Resolution: fixed
Status: closedreopened

comment:8 Changed 8 years ago by Raphaël Braud

Resolution: worksforme
Status: reopenedclosed
Note: See TracTickets for help on using tickets.
Back to Top