Automated notification of documentation fall-out-of-sync

[orpheuslummis]

John's idea:

The medium-term goal in-lieu of swimm is for the docs repo to have all the projects it covers (defra, orbis, lens, etc...) work as git-submodules, and the GithubActions system provide automation to notify if/when something falls out of sync. Then ensuring that each "codeblock" or something in the public docs, is linked to a specific Line(s) of code, so if the code changes (in a meaninful way) on the source repo, then we get visibility/automation on the docs repo.

Swimm is nice because all the platform metadata for linking docs/code was embedded as markdown data. Possibly extend that

[jsimnz]

Throwing this on the wall as a continuation of the blurb above:

• Triggering actions on submodule updates: https://thenewstack.io/how-to-trigger-github-actions-on-submodule-updates/

  • Every submodule update, parse the changes and see if they coorelate to linked snippets/docs in the parent (docs) repo

• AST focus git diff: https://github.com/Wilfred/difftastic

  • Use AST semantics within the diff algorithm for submodule comparison to tracking meaningful changes (and non-changes), to better couple the docs and code

[jsimnz]

More ideas

• https://github.com/temporalio/snipsync
• https://github.com/temporalio/docusaurus-plugin-snipsync