Docstrings highlighting with pygments

[nastasi-oq]

Currently:

• tests are missing

[carltongibson]

👀s good.

[nastasi-oq]

QUESTION @carltongibson: looking to adding test I found that apply_markdown(text): function (https://github.com/encode/django-rest-framework/blob/master/rest_framework/compat.py#L233)
has more or less the same behavior of render_markdown(markdown_text) function (https://github.com/encode/django-rest-framework/blob/master/rest_framework/templatetags/rest_framework.py#L70) but the first has tests and a better convertion in case markdown package is not present.
There is any particular reason because render_markdown isn't a simple wrapper of apply_markdown ?

[carltongibson]

@nastasi-oq I think “accident of history” is probably the simplest answer.

I’m happy to see a refactoring here but it might be better to handle it in two steps. This PR adding the new functionality, not worrying about duplication. Then another PR handling the refactoring. This makes each step easier to review, and complete. Sound ok to you?

[nastasi-oq]

@carltongibson IMHO there are 2 options:

1. do what you suggest but in the reverse order
2. do all in a single PR
   The reason is that extend the current test for apply_markdown is far simple and fast than develop a new one that in the second PR will be removed.
   If I have enough time before release I can do 1.

[nastasi-oq]

@carltongibson new PR opened to refactor render_markdown: #5469

[nastasi-oq]

@carltongibson for me is final.

[carltongibson]

This is lovely. Nice small footprint. Thanks for the work!

[nastasi-oq]

I'm glad to contribute to DRF.

[dmwyatt]

@nastasi-oq Where did this @@ method of marking code blocks come from? Is that a standard somehwere or just something implemented here?

I ask because it's pretty widespread to mark code blocks in markdown with triple backticks. For example, that's how you mark code blocks here on github.

[nastasi-oq]

@dmwyatt just from the example that I found (and that is credited in the code), if you think to be better change it in another syntax I'm not against.

[dmwyatt]

@carltongibson What do you think?

To be clear on what I'm talking about, this PR uses a format that is not used in any other markup system that I can find. Specifically, to mark a code block with this PR you do something like:

@@ json @@
['some json here']
@@

This '@@' markup is what I'm talking about.

Here on github and lots of other places you use triple backticks to markup code blocks. Of course, I don't think the Markdown "standard" (such as it is) has any method of marking code blocks, but I think triple backticks are widely-supported.

I propose code blocks be marked like:

```json
['some json here']
\```

(that extra backslash is just so I can fool githubs markdown parsing to let me put triple backticks inside a code block marked out by triple backticks)

[carltongibson]

Yep. I’d happily review a PR making an adjustment here. I’m not particularly worried about the block markers, but the triple back ticks are widely used.

(In a way it would be nice to allow the markdown processor to be pluggable. I suspect that’s not going to be a hook we’d want to expose.)

[nastasi-oq]

@carltongibson always happy to make people happy: review it 😜 !