Refactor.

Author: samsrabin

build_docs_to_publish

@@ -18,6 +18,7 @@ from doc_builder.build_docs import (
     main as build_docs,
 )
 from doc_builder.build_docs_shared_args import main as build_docs_shared_args
+from doc_builder.sys_utils import get_git_head_or_branch, check_permanent_file
 
 # Change to the parent director of doc-builder and add to Python path
 os.chdir(os.path.join(os.path.dirname(__file__), os.pardir))
@@ -40,36 +41,6 @@ STATIC_DIR = os.path.join(SOURCE, "_static")
 TEMPLATES_DIR = os.path.join(SOURCE, "_templates")
 
 
-def get_git_head_or_branch():
-    """
-    Get the name of the current branch. If detached HEAD, get current commit SHA.
-    """
-    try:
-        result = subprocess.run(
-            ["git", "symbolic-ref", "--short", "-q", "HEAD"],
-            stdout=subprocess.PIPE,
-            stderr=subprocess.DEVNULL,
-            text=True,
-            check=True,
-        )
-        output = result.stdout.strip()
-    except subprocess.CalledProcessError:
-        output = ""
-
-    if not output:
-        # Fallback to commit SHA
-        result = subprocess.run(
-            ["git", "rev-parse", "HEAD"],
-            stdout=subprocess.PIPE,
-            stderr=subprocess.DEVNULL,
-            text=True,
-            check=True,
-        )
-        output = result.stdout.strip()
-
-    return output
-
-
 def checkout_and_build(version, args):
     """
     Check out docs for a version and build
@@ -82,21 +53,9 @@ def checkout_and_build(version, args):
     # the permanent_files list.
     permanent_files = [CONF_PY, VERSIONS_PY, STATIC_DIR, TEMPLATES_DIR, "doc-builder"]
 
-    # Check "permanent" files: Each should (a) exist and (b) not have any uncommitted changes.
+    # Check some things about "permanent" files before checkout
     for filename in permanent_files:
-        # Error if doesn't exist
-        if not os.path.exists(filename):
-            raise FileNotFoundError(filename)
-        # Error if it contains uncommitted changes
-        cmd = f"git add . && git diff --quiet {filename} && git diff --cached --quiet {filename}"
-        try:
-            subprocess.check_output(cmd, shell=True)
-        except subprocess.CalledProcessError as e:
-            subprocess.check_output(
-                "git reset", shell=True
-            )  # Unstage files staged by `git add`
-            msg = f"Important file/submodule may contain uncommitted changes: '{filename}'"
-            raise RuntimeError(msg) from e
+        check_permanent_file(filename)
 
     # Check out the git reference of this version (branch name, tag, or commit SHA)
     subprocess.check_output("git checkout " + version.ref, shell=True)

doc_builder/sys_utils.py

@@ -6,6 +6,57 @@
 import os
 
 
+def check_permanent_file(filename):
+    """
+    Check a "permanent" file (one that we don't want to change between doc version builds)
+    """
+
+    # Ensure file exists
+    if not os.path.exists(filename):
+        raise FileNotFoundError(filename)
+
+    # Error if file contains uncommitted changes
+    cmd = f"git add . && git diff --quiet {filename} && git diff --cached --quiet {filename}"
+    try:
+        subprocess.check_output(cmd, shell=True)
+    except subprocess.CalledProcessError as e:
+        subprocess.check_output(
+            "git reset", shell=True
+        )  # Unstage files staged by `git add`
+        msg = f"Important file/submodule may contain uncommitted changes: '{filename}'"
+        raise RuntimeError(msg) from e
+
+
+def get_git_head_or_branch():
+    """
+    Get the name of the current branch. If detached HEAD, get current commit SHA.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "symbolic-ref", "--short", "-q", "HEAD"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            check=True,
+        )
+        output = result.stdout.strip()
+    except subprocess.CalledProcessError:
+        output = ""
+
+    if not output:
+        # Fallback to commit SHA
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            check=True,
+        )
+        output = result.stdout.strip()
+
+    return output
+
+
 def git_current_branch():
     """Determines the name of the current git branch