Refs #20910 -- Replaced snippet directive with code-block.

[funkybob]

Any reasons for our custom "snippet::" directive in the docs appear to have long passed into invalid obscurity.
I've replaced all uses with code-block, with a view to later being able to use :emphasize-lines: to further improve the docs.

[carltongibson]

Hey @funkybob.

This looks super thank you!

There was a flake8 failure, so I pushed a fix for that. (You can either squash or we can do it when merging.)

The changes look good and build without error, so 👍 as far as I can see.

Any reasons for our custom "snippet::" directive in the docs appear to have long passed into invalid obscurity.

😄 I'm not sure what those reasons were, so I'll just leave this sitting here for a while in case anyone shouts.

[funkybob]

I caught @ubernostrum on IRC who believed it was to add the :filename: directive, which the Sphinx docs say is what :caption: is for, so...

[carltongibson]

Thanks for the follow up! Good info. 👍🏽

[claudep]

Looks good, thanks!

[carltongibson]

Since this is a docs fix, we'd normally back port to 2.1. I'm not sure about that though because of the code change. (Surely no-one is using this code but...)

One solution would be to split into two commits. One to just the docs using code-block and the other removing the snippet directive. Then we could back port just the one. ???

The other is to delay back porting (which we could do if/when we found conflicts occurring.)

I'll hold off for now.

[timgraham]

This needs to be tested with djangoproject.com. Some changes may also be needed there, e.g. 1be2165 and the "copy to clipboard" feature. Probably it's fine to backport to 2.1 but since the older versions of the docs still use snippet, djangoproject.com will have to work with both.