Mkdocs preprocess hooks

[ADBond]

Type of PR

• BUG
• FEAT
• MAINT
• DOC

Is your Pull Request linked to an existing Issue or Pull Request?

Closes #1395, and fixes the cludges of my own making.

Give a brief description for the solution you have provided

This adds a docs dependency mkdocs-simple-hooks which allows straightforward access to hooks in the mkdocs build process without writing a fully-fledged plugin.

In this case I have added a hook on_page_markdown which replaces the text of the markdown files in the build, specifically the two functions of the previous script scripts/preprocess_markdown_includes.py:

• including markdown, mimicking the functionality of mkdocs-include-markdown-plugin, which we don't use as it clashes with mknotebooks (see Automatically add tables of comparison (level)s compatible with each dialect to docs #1035, Fix docs workflow #1073)
• rewriting links from CONTRIBUTING.md to make them compatible with the docs structure (see CI link-checking + fixed links #1902).

This in particular means that for local builds we don't actually change the files that need their contents altering, which is irritating, and risks them being accidentally committed (and thus have their contents baked-in from that point onwards, rather than being dynamically generated).

This branch is built from this new process, and has the correct tabular content + links.

Limitations and future

The link-rewriting functionality is a little brittle, using the title of the (currently) only page this is relevant to. As it's only used for this one file, it is probably okay for now and not worth the increased complexity of a more general solution, but might need altering if this portion ends up being used more (probably not too likely - only relevant for files that live outside of docs/ that we also want to include in the build).

With these hooks a nice future option could be to actually generate the included files dynamically as part of the build also, rather than having the initial 'generation' step. This would make building more straightforward (both locally and in CI), although there might be issues with dependency clashing (see #1035), and not sure if this might slow things down.

PR Checklist

• Added documentation for changes
• Added feature to example notebooks or tutorial (if appropriate)
• Added tests (if appropriate)
• Updated CHANGELOG.md (if appropriate)
• Made changes based off the latest version of Splink
• Run the linter

[RossKen]

This is a nifty solution! 🎉

On your point of the "brittleness" - I think this is a major improvement on the current process and I am happy to kick that can down the road a bit tbh. Any additions outside of the docs folder will be very rare so I don't see it as much of an issue.