SUP-31 Code Snippet Utilities

[pj-simpson]

The Code Snippets in the markdown files are BAD.

They are old and out of date, because they were written by hand a few years ago, and this creates issues for our clients.

THE LONG TERM VIEW:

Have utilities in this repo which can scan, find and test the correctness of the code snippets in our docs.

THIS COMMIT:

• Creates a code_utils directory which is a uv-based python project.
• Creates an extract_code_from_files script which will search through the docs/ directory and make a list of all markdown files which contain code snippets. It will then create a temp directory with subdirectories for each supported language and then place each snippet in its own file.

• Updates the .gitignore file, so we don't check these generated files into source control.

The idea being that the code snippets extracted into files could potentially be run or linted in some kind of containerized/ sandboxed environment and we could obtain greater confidence in the code we have in our docs.

COMING UP

Script to remove a programming language (we need to do this for Go!)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
codat-docs	Ready	Preview	Comment	Sep 5, 2025 2:11pm

[github-actions]

Overall readability score: 57.78 (🔴 -0.09)

File	Readability
README.md	11.19 (-)

View detailed metrics

🟢 - Shows an increase in readability
🔴 - Shows a decrease in readability

File	Readability	FRE	GF	ARI	CLI	DCRS
README.md	11.19	17.34	17.33	20.7	19	9.89
	-	-	-	-	-	-

Averages:

	Readability	FRE	GF	ARI	CLI	DCRS
Average	57.78	48.51	10.37	11.6	12.13	7.83
	🔴 -0.09	🔴 -0.06	🔴 -0.01	🔴 -0.02	🔴 -0.01	🟢 +0

View metric targets

Metric	Range	Ideal score
Flesch Reading Ease	100 (very easy read) to 0 (extremely difficult read)	60
Gunning Fog	6 (very easy read) to 17 (extremely difficult read)	8 or less
Auto. Read. Index	6 (very easy read) to 14 (extremely difficult read)	8 or less
Coleman Liau Index	6 (very easy read) to 17 (extremely difficult read)	8 or less
Dale-Chall Readability	4.9 (very easy read) to 9.9 (extremely difficult read)	6.9 or less

[github-actions]

Link check results for preview deployment (https://codat-docs-git-the-code-snippet-sorter-codat.vercel.app):

[
  "[401] https://codat-docs-git-the-code-snippet-sorter-codat.vercel.app/"
]

[pj-simpson]

Oh! Cursor Penance:

Obviously this was done with the assistance of Cursor.

I have personally read and made sure I understand each line of code.

In order to ensure this, I refactored the 'function based' approach Cursor takes to an OOP one using a Class.

Cursor also opted to use the os module, when pathlib is generally considered a more modern option. I got Cursor to walk through the os => pathlib upgrade function by function.

[dcoplowe]

The code snippets contain variables that are related between the various snippets. How can we continue to support this?

[pj-simpson]

@dcoplowe : that's good to know. This utility, so-far, just gives us an audit of what snippets there are currently in the docs.

What I would like to build towards is effectively a hybrid of a kind of coverage-report/smoke test of the code snippets. As I see it, nothing in these utilities would actually write new or re-write existing snippets, (that's a different job). We're using this to finding snippets, and then extracting a copy so that they can be linted/ run or tested elsewhere... does that make sense?