Documentation on template tag render() methods is inconsistent with core tags.

[Keryn Knight <django@…>]

According to the ​documentation:

render() should never raise TemplateSyntaxError or any other exception. It should fail silently, just as template filters should.

As I write this, at a glance, ​URLNode.render(), ​WidthRatio.render(), both raise TemplateSyntaxError. So do some of those outside defaulttags, such as ​CacheNode.render(), and it looks like ​ExtendsNode.get_parent() does too (ForLoopNode.render() does, but is exempted from this list because it explicitly only does so if TEMPLATE_DEBUG is True)

I'm marking this as a documentation issue, as I think the wording should be changed to reflect that ideally template tags should fail silently [at least in production, where DEBUG and TEMPLATE_DEBUG should be False], but it is understandable that sometimes they cannot, which is I assume why Django hasn't "dogfooded" it's own advice here.

The links above should all be to the files/documentation as they stand when writing this, pinned to 1.6 or the last commit for temporal accuracy going forwards.

[Daniele Procida]

I've marked this ticket as especially suitable for first-time committers or people following the ​Don't be afraid to commit tutorial. If you're tackling this ticket, please don't hesitate to ask me for guidance if you'd like any, either here or on the Django IRC channels, where I can be found as EvilDMP.

[Bouke Haarsma]

I've proposed a change in this PR: ​https://github.com/django/django/pull/1737.

[Tim Graham <timograham@…>]

In e077224f4ad69a68ae58a373ef69941272d3656c:

Fixed #20962 -- Documented that template tag render() may raise exceptions.

Thanks Keryn Knight for the report.

[Tim Graham <timograham@…>]

In 7f62d794b303bedfd094742a84dcc8b85df3ba8b:

[1.5.x] Fixed #20962 -- Documented that template tag render() may raise exceptions.

Thanks Keryn Knight for the report.

Backport of e077224f4a from master

[Tim Graham <timograham@…>]

In 7f566fdb4c8453c8fa4b44d0fe5cc28472acc2ff:

[1.6.x] Fixed #20962 -- Documented that template tag render() may raise exceptions.

Thanks Keryn Knight for the report.

Backport of e077224f4a from master