Opened 9 years ago

Closed 7 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:


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

A docstring on a view such as this:

def foo(request):
    return None

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


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

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

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 9 years ago by Noah Slater <nslater@…>

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

comment:2 Changed 9 years ago by SmileyChris

  • Triage Stage changed from Unreviewed to Design decision needed

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

comment:3 Changed 9 years ago by mtredinnick

  • Triage Stage changed from Design decision needed to Accepted

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 7 years ago by lukeplant

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 7 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 7 years ago by raphael

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

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

Closing ticket...

comment:7 Changed 7 years ago by raphael

  • Resolution fixed deleted
  • Status changed from closed to reopened

comment:8 Changed 7 years ago by raphael

  • Resolution set to worksforme
  • Status changed from reopened to closed
Note: See TracTickets for help on using tickets.
Back to Top