allow adding other languages in source code documentation

[skriptix]

Hi folks, many thanks for this great framework!!!

Description

The source code snippets shown in the API documentation are great, but up not now not adaptable. I would like to add source code snippets for different languages or for using the interface via a special wrapper library, which is used in our project to route requests depending on being on a productive or a staging system.

To have a chance to inject a modified version of DocumentationRenderer, the parameter renderer_classes has been added to documentation.include_docs_urls(). Now i can e.g. reduce
the number of displayed source code languages (and modify the ordering) like this:

from rest_framework.renderers import DocumentationRenderer, CoreJSONRenderer

class MyDocumentationRenderer(DocumentationRenderer):
    languages = ['python', 'shell']

renderer_classes = [MyDocumentationRenderer, CoreJSONRenderer]

urlpatterns = [                                                                                                
    url(r'^docs/', include_docs_urls(title='My API', renderer_classes=renderer_classes)),
       :

To make this work some of the HTML templates have been adapted as well.

By adding new language names and providing the appropriate templates, it is now even possible to add new language snippets to the API documentation.

What do you think?

Thanks and Regards,

Georg

[carltongibson]

@skriptix. This looks good. (Sorry for the slow response.)

Are you up for bringing this up to date? If so, it seems a reasonable addition.

[skriptix]

@carltongibson Sorry, I am not sure what you are asking for. "bringing this up to date" sounds like you did have some sort of meeting?

[skriptix]

Ok, now i got it. You want me to resolve the conflicts. I will have a look!

[skriptix]

@carltongibson Hi, the branch is up to date now. Thanks for giving it a try!

[carltongibson]

👌🏼 awesome I’ll have a look next week.

Current thought is to take this as is but create a new ticket for documenting the templates in API docs, so users then know how to override.

Since there are currently no such docs I don’t want to hold this up for that.

Thanks for the effort!

[carltongibson]

OK. Looks good.

I'm going to milestone for v3.8 to allow a little more time to review.

At a minimum we'll need to add docs for the new parameters to get_docs_view etc. I think we also need to document the process of subclassing DocumentationRenderer here. (In the end I, in fact, do think the PR isn't really complete without that.)

This is a good feature though. We should definitely have it. 👍

[carltongibson]

Closing in favour of #5752. Thanks for the effort @skriptix!