Fixes #17860. Briefly, to reproduce this bug:

1. Create a file included.rst with a plot inside it.

2. Create a file index.rst containing the include directive
   .. include:: included.rst.

3. Build Sphinx documentation.

4. Modify the plotting code inside included.rst, but don't touch
   index.rst.

5. Rebuild the Sphinx documentation. Because index.rst wasn't touched,
   plot_directive thinks that it's up-to-date and thus the image doesn't
   need to be re-created.

This commit fixes the issue by checking the modification times not only
of the source file (index.rst in this case), but also of the file(s)
included within it (included.rst).

PR Summary

The commit message contains most of the info, but I attach some extra detail here just in case people come across it and find it useful. There are a couple of ways to get the included files:

Method 1

Since docutils 0.17, there is an attribute state.document.include_log which is a list of tuples containing the names of any files that were included, which is exactly what we want.

[('index.rst', (None, None, None, None), 4.611686018427388e+18),
 ('included.rst', (None, None, None, None), 21)]

Method 2

Directly inspect state_machine.input_lines.items, which is a list of tuples (source, offset). If a RST file is included, then we can get its filename (relative to the top-level Sphinx directory) in source. For example, this is what plot_directive can when I place .. include:: included.rst inside the file ~/test/plot_dir/index.rst:

[('included.rst', 2),
 ('included.rst', 3),
 ('included.rst', 4),
 ('included.rst', 5),
 ('included.rst', 6),
 ('included.rst', 7), 
 ('included.rst', 8),
 ('included.rst', 9),
 ('included.rst', 10),
 ('included.rst', 11),
 ('included.rst', 12),
 ('internal padding after included.rst', 13),
 ('/Users/yongrenjie/test/plot_dir/index.rst', 7),
 ('/Users/yongrenjie/test/plot_dir/index.rst', 8),
 ('/Users/yongrenjie/test/plot_dir/index.rst', 9),
 ('/Users/yongrenjie/test/plot_dir/index.rst', 10),
 ('/Users/yongrenjie/test/plot_dir/index.rst', 11),
 ('/Users/yongrenjie/test/plot_dir/index.rst', 12),
 ('/Users/yongrenjie/test/plot_dir/index.rst', 13),
 ('/Users/yongrenjie/test/plot_dir/index.rst', 14),
 ('/Users/yongrenjie/test/plot_dir/index.rst', 15),
 ('/Users/yongrenjie/test/plot_dir/index.rst', 16),
 ('/Users/yongrenjie/test/plot_dir/index.rst', 17),
 ('/Users/yongrenjie/test/plot_dir/index.rst', 18)
]

The issue with this is that there's the 'internal padding after...' line which we would have to filter out, and I'm not sure what other directives (if any) might also add some junk to this list. I got around this by first removing duplicates and then checking which of the entries were valid files.

I feel like Method 2 is a bit fragile, so I made it as a fallback:

try:
    # method 1...
except AttributeError:    # indicates docutils <=0.16
    # method 2...

I've tested this all the way back to docutils 0.14 and it seems to be pretty reliable.

PR Checklist

• N/A 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.
• N/A 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).