Give plot_directive output a max-width: 100%

[brunobeltran]

PR Summary

Currently, non-sphinx-gallery plots in the documentation (for example, from a .. plot:: directive in a docstring) produce plots that do not scale with screen size. This means that on e.g. phones, the plots get chopped off, as seen here:

Other Sphinx extensions (gallery, the inheritance diagram extension, etc) add their own custom CSS to make the images fit in the page. I copied the approach taken by sphinx.ext.graphviz to get the following result:

This became increasingly important for my GSOD work (e.g. #18544, where the API docs center around the inclusion of a "demo" figure showing the various options).

Edit: additionally, I had to fix an existing bug in plot_directive.TEMPLATE that caused Sphinx to warn (failing our tests) whenever there is both a caption and a custom class assigned to a figure.

PR Checklist

• Has pytest style unit tests (and pytest passes).
• Is Flake 8 compliant (run flake8 on changed files to check).
• [N/A] New features are documented, with examples if plot related.
• Documentation is sphinx and numpydoc compliant (the docs should build without error).
• Conforms to Matplotlib style conventions (install flake8-docstrings and run flake8 --docstring-convention=all).
• [N/A] New features have an entry in doc/users/next_whats_new/ (follow instructions in README.rst there).
• [N/A] API changes documented in doc/api/next_api_changes/ (follow instructions in README.rst there).

[brunobeltran]

As found in https://github.com/sphinx-doc/sphinx/blob/3.x/sphinx/ext/graphviz.py#L390

[brunobeltran]

Stripping trailing whitespace here causes the extra whitespace from before the {% if it matches to be effectively prepended to the caption, causing a bug.

Stripping that earlier whitespace using {% - if doesn't work because then Jinja strips the newline separating the options from the content.

So I settled for this ugly solution which puts "{{ caption }}" up against the side.

The other option would be to remove the artificially-inserted leading whitespace from the first line of the "caption" (L758), but this would technically be changing API for users who already have made custom templates for use the with plot_directive.

[brunobeltran]

Sphinx includes some copyright/license stuff here, presumably since this file will be redistributed independently of the repository. I figure I don't mind my whole three lines of very advanced CSS becoming public domain upon distribution, but wanted to flag this in case there are legal ramifications I don't understand.

https://github.com/sphinx-doc/sphinx/blob/3.x/sphinx/templates/graphviz/graphviz.css#L7

[brunobeltran]

This caption is repeated verbatim after each plot with my changes. This may not be what I would have expected to happen, but it is the existing behavior.