Fixes#17860. Briefly, to reproduce this bug:

1. Create a fileincluded.rst with a plot inside it.

2. Create a fileindex.rst containing the include directive
   .. include:: included.rst.

3. Build Sphinx documentation.

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

5. Rebuild the Sphinx documentation. Becauseindex.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 attributestate.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 inspectstate_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) insource. For example, this is whatplot_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 (andpytest passes).
• IsFlake 8 compliant (runflake8 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 shouldbuild without error).
• Conforms to Matplotlib style conventions (installflake8-docstrings and runflake8 --docstring-convention=all).
• N/A New features have an entry indoc/users/next_whats_new/ (follow instructions in README.rst there).
• N/A API changes documented indoc/api/next_api_changes/ (follow instructions in README.rst there).