Escaped documentation in admin site

[Noah Slater <nslater@…>]

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.

[Noah Slater <nslater@…>]

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

[Chris Beaven]

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

[Malcolm Tredinnick]

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.

[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.

[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.

[Raphaël Braud]

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

Closing ticket...