From d08a5f03fa52cf53d53e2f839c46b79efaa68eae Mon Sep 17 00:00:00 2001
From: Paul Prescod <pprescod@salesforce.com>
Date: Fri, 9 Apr 2021 17:52:53 -0700
Subject: [PATCH 1/2] Pre-commit hook to keep docs and examples in sync

---
 .pre-commit-config.yaml |  8 ++++++++
 docs/index.md           |  1 +
 examples/company.yml    |  2 --
 tests/test_embedding.py |  6 +++---
 tools/docs_samples.py   | 35 ++++++++++++++++++++++++++++++-----
 5 files changed, 42 insertions(+), 10 deletions(-)
 mode change 100644 => 100755 tools/docs_samples.py

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 6e4b1765..4a711b9e 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -10,3 +10,11 @@ repos:
     hooks:
     - id: check-merge-conflict
     - id: flake8
+- repo: local
+  hooks:
+    - id: merge-docs
+      name: Merge examples into docs
+      entry: tools/docs_samples.py
+      language: python
+      files: ".*.md"
+      always_run: true
diff --git a/docs/index.md b/docs/index.md
index 232d1611..c61f8bd8 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1027,6 +1027,7 @@ And then you pass that option like this:
 You can learn the list of options available in the latest version
 like this:
 
+```s
 $ snowfakery --help
 Usage: snowfakery [OPTIONS] YAML_FILE
 
diff --git a/examples/company.yml b/examples/company.yml
index 4baad929..7bf28d5c 100644
--- a/examples/company.yml
+++ b/examples/company.yml
@@ -1,5 +1,3 @@
-- option: A # used for a pytest
-  default: AA
 - object: Company
   fields:
     Name:
diff --git a/tests/test_embedding.py b/tests/test_embedding.py
index 80042dfc..629ed6e4 100644
--- a/tests/test_embedding.py
+++ b/tests/test_embedding.py
@@ -21,9 +21,9 @@ def test_arguments(self):
             outfile = Path(t) / "foo.txt"
             continuation = Path(t) / "out.yml"
             generate_data(
-                yaml_file="examples/company.yml",
-                user_options={"A": "B"},
-                target_number=(20, "Employee"),
+                yaml_file="tests/BDI_generator.yml",
+                user_options={"num_accounts": "15"},
+                target_number=(20, "Account"),
                 debug_internals=True,
                 output_format="json",
                 output_file=outfile,
diff --git a/tools/docs_samples.py b/tools/docs_samples.py
old mode 100644
new mode 100755
index acda0098..b0f1ec71
--- a/tools/docs_samples.py
+++ b/tools/docs_samples.py
@@ -1,9 +1,16 @@
+#!/usr/bin/env python3
 from pathlib import Path
+from glob import glob
+from difflib import context_diff
 
 # This tool merges example files into the docs and thus ensures
 # that the tested version of the example is also the one in the
 # doc.
 
+being_replaced = []
+being_replaced_filename = None
+replacement = None
+
 
 class TOP:
     """Top level of the Markdown doc"""
@@ -27,13 +34,23 @@ def next_state(line, location):
 
 
 class REPLACING:
-    """Code example is open being replaced because it corresponds to a file on disk"""
+    """Code example is being replaced because it corresponds to a file on disk"""
 
     def next_state(line, location):
         if line.startswith(TRIPLE_QUOTE):
             check_triple_quote_alone(line, location)
+            if replacement != being_replaced:
+                for diff in context_diff(
+                    replacement,
+                    being_replaced,
+                    fromfile=being_replaced_filename,
+                    tofile="Docs",
+                ):
+                    print(diff, end="")
+            being_replaced.clear()
             return TOP, [line]
         else:
+            being_replaced.append(line)
             return REPLACING, []  # IGNORE lines to be replaced
 
 
@@ -41,12 +58,14 @@ class START_EXAMPLE:
     """First line of a code example"""
 
     def next_state(line, location):
+        global replacement, being_replaced_filename
         if line.startswith("#"):
             filename = line.split("#")[1].strip()
             assert Path(filename).exists(), location
             with Path(filename).open() as f:
                 example_lines = f.readlines()
-            print("Replacing", filename)
+            replacement = example_lines
+            being_replaced_filename = filename
             return REPLACING, [line] + example_lines
         else:
             return OPEN, [line]
@@ -78,12 +97,18 @@ def replace_samples(input_file) -> str:
     return "".join(output)
 
 
-def main(filename):
+def replace_examples(filename):
     with open(filename) as f:
         output = replace_samples(f)
     with open(filename, "w") as f:
         f.write(output)
 
 
-filename = "docs/index.md"
-main(filename)
+def main():
+    filenames = glob("docs/*.md")
+    for filename in filenames:
+        replace_examples(filename)
+
+
+if __name__ == "__main__":
+    main()

From 9e0864ee9ca79e9507c0e491c832aca5e6d100c7 Mon Sep 17 00:00:00 2001
From: Paul Prescod <pprescod@salesforce.com>
Date: Mon, 12 Apr 2021 16:57:52 -0700
Subject: [PATCH 2/2] Run only as needed

---
 .pre-commit-config.yaml | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 4a711b9e..d1d5cbaa 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -16,5 +16,4 @@ repos:
       name: Merge examples into docs
       entry: tools/docs_samples.py
       language: python
-      files: ".*.md"
-      always_run: true
+      files: ".*.md|examples/.*.yml"