Previously, sphinx-apidoc would always write files, even if the
auto-generated content was identical. This would bump the mtime and
cause the file to be re-read and generated on the next build invocation.
After this patch, the files are not written unless content has changed.
In a contrived example using `sphinx-apidoc` to regenerate documentation
for CPython's Lib/ directory, this patch reduced the number of "updated"
source files from 257 to 2. Execution time of `sphinx-build` without
parallelism decreased from ~12.5s to ~4.5s.
Sphinx relies on file mtimes to determine whether operations such as
source reading need to occur.
When tools like sphinx-apidoc run, they blindly write files, updating the
mtime of files, even if the final file content does not change.
In this patch, we introduce a FileAvoidWrite class that can be used to
only write files if content has changed. This opens the door to less
cache invalidation via mtime changes and thus better performance. This
will be realized in a subsequent commit.
Gregory Szorc