Use validated SignalK json in all documentation

[bkp7]

In order to ensure that all json examples and explanations within the documentation are valid and up to date, I propose that they are automatically generated from json files which have already been validated by the test suite.

A proof of concept here, shows how this could work allowing for the current documentation style to remain unaltered, but be guaranteed to represent the latest schemas.

Comments on this approach please....

[tkurki]

This sounds very good! I had thoughts of doing this in a gitbook plugin as part of the gitbook process. You have pretty much implemented the features I had in mind. The exact details of the snippet picking expression are not very important, this is not something you do all the time. Is there an easy way from the command line to test an expression?

Anyway, start with something and open a [WIP] named PR to get feedback.

Looking forward to this!

[bkp7]

I have updated the proof of concept here to include command line arguments including the ability to test an expression using eg

node mdInsert [mdInsert -jsonSnippet $..currentRadius](./docs/demo.json)

I was planning to add the document processing into the existing documentation workflow using npm. Is it even worth looking at implementing it as a gitbook plugin for our one use case? Let's see how the implementation looks when I do the WIP PR as you suggest.

[bkp7]

New PR #433 created which has all the changes required.

To experiment with fsnip capability on the command line use something like fsnip myfile.json --prettify. See fsnip for documentation.

The fsnip can be cut/pasted out of the SK markdown docs, but be aware that the file path is relative to the location of the document.