Improve user documentation of the spec

[FynnBe]

After some preliminary discussions (with @k-dominik @Tomaz-Vieira @esgomezm @akreshuk @cfusterbarcelo and others),
it is clear that should improve the user documentation of the spec.

Concretely https://github.com/bioimage-io/spec-bioimage-io/blob/main/scripts/generate_spec_documentation.py needs an update

and we should try to export an intermediate json file with the content of the spec documentation.

[esgomezm]

Hi! I checked but I'm struggling to understand this file, sorry. In particular, what's the input to the file? If it's the code (bioimageio library itself), where can we start editting it?

[FynnBe]

the current md user docs are generated by https://github.com/bioimage-io/spec-bioimage-io/blob/main/scripts/generate_spec_documentation.py