Use FileAvoidWrite in apidoc

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.

AUTHORS

@@ -48,6 +48,7 @@ Other contributors, listed alphabetically, are:
 * Jeppe Pihl -- literalinclude improvements
 * Rob Ruana -- napoleon extension
 * Stefan Seefeld -- toctree improvements
+* Gregory Szorc -- performance improvements
 * Shibukawa Yoshiki -- pluggable search API and Japanese search
 * Antonio Valentino -- qthelp builder
 * Pauli Virtanen -- autodoc improvements, autosummary extension

CHANGES

@@ -7,6 +7,10 @@ Incompatible changes
 Features added
 --------------
 
+* apidoc now avoids invalidating cached files by not writing to files whose
+  content doesn't change. This can lead to significant performance wins if
+  apidoc is run frequently.
+
 Bugs fixed
 ----------
 

sphinx/apidoc.py

@@ -21,7 +21,7 @@ import sys
 import optparse
 from os import path
 
-from sphinx.util.osutil import walk
+from sphinx.util.osutil import FileAvoidWrite, walk
 from sphinx import __display_version__
 
 # automodule options
@@ -61,11 +61,8 @@ def write_file(name, text, opts):
         print('File %s already exists, skipping.' % fname)
     else:
         print('Creating file %s.' % fname)
-        f = open(fname, 'w')
-        try:
+        with FileAvoidWrite(fname) as f:
             f.write(text)
-        finally:
-            f.close()
 
 
 def format_heading(level, text):