Clarify docs for render_to_response and context_instance deprecation

[Mark Tranchant]

The ​render_to_response() documentation notes the deprecation of the context_instance argument:

"Deprecated since version 1.8: The context_instance argument is deprecated. Simply use context."

This advice is singularly unhelpful — it took me a fair amount of StackOverflow searching to work out what to do. I use the RequestContext to handle user messages and authorization, so it's essential for my project.

I'd suggest the note should read:

"Deprecated since version 1.8: The context_instance argument is deprecated. Simply use render() with the request as the first argument."

I don't know if that covers all use cases for the deprecation notice: if not, the original should be expanded to provide a better explanation. I've dragged my project along since 0.96 so am a fairly old hand yet it didn't make sense to me.

[Aymeric Augustin]

Indeed, this seems to trip up people regularly.

I mistakenly assumed that in 2015 everyone would be lazy enough to use render()

[Tim Graham]

​PR

[Tim Graham <timograham@…>]

In 36d0aa43:

[1.9.x] Fixed #25963 -- Clarified render_to_response() context_instance deprecation.

[Tim Graham <timograham@…>]

In d156ae06:

[1.8.x] Fixed #25963 -- Clarified render_to_response() context_instance deprecation.

Backport of 36d0aa43036090685cebe6c9f757631cdadb1400 from stable/1.9.x

[Mark Tranchant]

Thanks, that's much clearer now. Should help other people in my position with older code being forced to update by the deprecation timeline.

[Tim Graham <timograham@…>]

In 28d05a4c:

Refs #25963 -- Fixed typo in docs/topics/http/shortcuts.txt

[Tim Graham <timograham@…>]

In 326efed:

[1.9.x] Refs #25963 -- Fixed typo in docs/topics/http/shortcuts.txt

Backport of 28d05a4c195e2e01cdbc1435d58b44ece5ccc170 from master