Bertrand Delacretaz wrote:
[...]
Seeing how hard it is to retrofit tests and docs to existing blocks, maybe we should require the following for any new non-scratchpad block:
-samples
-automated tests
-documentation (in the block itself, I don't think our docs structure makes it easy to integrate docs from blocks)
What documentation format would be required here?
I don't think any mechanism is in place currently to integrate documentation from blocks into the main docs. If I'm right, either something must be created, or we must accept whatever the blocks creators provide, as long as it gives sufficent info about the block. Good self-documenting samples might be ok for simple blocks.
Does it make sense to use the Forrest format (how would it be rendered)?
You could probably use the pipelines currently used to render docs locally. But if would be better to find a simple way to integrate blocks docs into the main docs, unfortunately I cannot help with this ATM.
-Bertrand
