From e47c681e9c252f0f4599f5c2f7b41ea13e4f05f3 Mon Sep 17 00:00:00 2001
From: lethosor <lethosor@gmail.com>
Date: Thu, 4 Aug 2022 02:07:52 -0400
Subject: [PATCH] Use write_file_if_changed() in changelog.py

Speeds up incremental builds significantly
---
 conf.py                                    | 25 ++++------------------
 docs/sphinx_extensions/dfhack/changelog.py |  4 ++--
 docs/sphinx_extensions/dfhack/util.py      | 20 +++++++++++++++++
 3 files changed, 26 insertions(+), 23 deletions(-)

diff --git a/conf.py b/conf.py
index e8ff8392b..49d005f46 100644
--- a/conf.py
+++ b/conf.py
@@ -14,9 +14,7 @@ serve to show the default.
 
 # pylint:disable=redefined-builtin
 
-import contextlib
 import datetime
-import io
 import os
 import re
 import shlex  # pylint:disable=unused-import
@@ -46,6 +44,10 @@ if os.environ.get('DFHACK_DOCS_BUILD_OFFLINE'):
 from docutils import nodes
 from docutils.parsers.rst import roles
 
+sys.path.append(os.path.join(os.path.abspath(os.path.dirname(__file__)), 'docs', 'sphinx_extensions'))
+from dfhack.util import write_file_if_changed
+
+
 def get_keybinds(root, files, keybindings):
     """Add keybindings in the specified files to the
     given keybindings dict.
@@ -145,23 +147,6 @@ def get_tags():
     return tags
 
 
-@contextlib.contextmanager
-def write_file_if_changed(path):
-    with io.StringIO() as buffer:
-        yield buffer
-        new_contents = buffer.getvalue()
-
-    try:
-        with open(path, 'r') as infile:
-            old_contents = infile.read()
-    except IOError:
-        old_contents = None
-
-    if old_contents != new_contents:
-        with open(path, 'w') as outfile:
-            outfile.write(new_contents)
-
-
 def generate_tag_indices():
     os.makedirs('docs/tags', mode=0o755, exist_ok=True)
     with write_file_if_changed('docs/tags/index.rst') as topidx:
@@ -225,8 +210,6 @@ generate_tag_indices()
 
 # -- General configuration ------------------------------------------------
 
-sys.path.append(os.path.join(os.path.abspath(os.path.dirname(__file__)), 'docs', 'sphinx_extensions'))
-
 # If your documentation needs a minimal Sphinx version, state it here.
 needs_sphinx = '1.8'
 
diff --git a/docs/sphinx_extensions/dfhack/changelog.py b/docs/sphinx_extensions/dfhack/changelog.py
index 2f27590fd..0cd732988 100644
--- a/docs/sphinx_extensions/dfhack/changelog.py
+++ b/docs/sphinx_extensions/dfhack/changelog.py
@@ -6,7 +6,7 @@ import sys
 
 from sphinx.errors import ExtensionError, SphinxError, SphinxWarning
 
-from dfhack.util import DFHACK_ROOT, DOCS_ROOT
+from dfhack.util import DFHACK_ROOT, DOCS_ROOT, write_file_if_changed
 
 CHANGELOG_PATHS = (
     'docs/changelog.txt',
@@ -172,7 +172,7 @@ def consolidate_changelog(all_entries):
 
 def print_changelog(versions, all_entries, path, replace=True, prefix=''):
     # all_entries: version -> section -> entry
-    with open(path, 'w') as f:
+    with write_file_if_changed(path) as f:
         def write(line):
             if replace:
                 line = replace_text(line, REPLACEMENTS)
diff --git a/docs/sphinx_extensions/dfhack/util.py b/docs/sphinx_extensions/dfhack/util.py
index 61f38b043..91f0accbe 100644
--- a/docs/sphinx_extensions/dfhack/util.py
+++ b/docs/sphinx_extensions/dfhack/util.py
@@ -1,3 +1,5 @@
+import contextlib
+import io
 import os
 
 DFHACK_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
@@ -6,6 +8,24 @@ DOCS_ROOT = os.path.join(DFHACK_ROOT, 'docs')
 if not os.path.isdir(DOCS_ROOT):
     raise ReferenceError('docs root not found: %s' % DOCS_ROOT)
 
+
+@contextlib.contextmanager
+def write_file_if_changed(path):
+    with io.StringIO() as buffer:
+        yield buffer
+        new_contents = buffer.getvalue()
+
+    try:
+        with open(path, 'r') as infile:
+            old_contents = infile.read()
+    except IOError:
+        old_contents = None
+
+    if old_contents != new_contents:
+        with open(path, 'w') as outfile:
+            outfile.write(new_contents)
+
+
 # directive argument helpers (supplementing docutils.parsers.rst.directives)
 def directive_arg_str_list(argument):
     """