Schema files are out of date

[jonnor]

To get out of this, we should make the schemas the canonical single-source-of-truth for all protocol description. Currently this information is in https://github.com/noflo/noflo.github.io/blob/master/documentation/_posts/2013-07-09-protocol.md
The human-readable documentation page should be generated from the JSON schemas

[jonnor]

Needed for flowbased/flowtrace#16

[jonnor]

Now we the prose in this project at https://github.com/flowbased/fbp-protocol/blob/master/spec/protocol.md and we generate docs from and autodeploy to: http://flowbased.github.io/fbp-protocol
So next step would be to migrate payload descriptions into the schemas, and generate the Markdown/HTML from that

[chadrik]

@jonnor, @ifitzpatrick and I can write a python script for this. I'm considering using jinja so that we can make a template .md file that loops over data pulled from the schema files. That will give us easy control over how the final doc is built.

[jonnor]

Cool. Yep, generating an .md for the things coming from schema (or a set of
.md files) will be easy to integrate with other doc-building tools.

On 18 May 2016 at 22:55, Chad Dombrova [email protected] wrote:

@jonnor https://github.com/jonnor, @ifitzpatrick
https://github.com/ifitzpatrick and I can write a python script for
this. I'm considering using jinja http://jinja.pocoo.org/ so that we
can make a template .md file that loops over data pulled from the schema
files. That will give us easy control over how the final doc is built.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#7 (comment)

Jon Nordby - www.jonnor.com

[jonnor]

Related to #17

[chadrik]

@jonnor #17 is pretty much ready to go. I think it just needs the flowtrace additions. Should we merge it in and then have you or @bergie update it with the flowtrace stuff?

[jonnor]

@chadrik reviewed and found some problems with #17, see latest comments there. I think we can do the tracing subprotocol after we merge that, though can't really close this issue until it is all in.

[chadrik]

Yep. Saw it and thanks for reviewing. Should be taken care of early next week.

[chadrik]

To close this ticket I think we just need the flowtrace stuff. @jonnor is that feature targeted for version 0.6 of the protocol?

[jonnor]

I think we should keep version bumps (like going to 0.6) to incompatible changes only.
The flowtrace stuff is only additions, and part of a new 'capability', and thus should not break any existing clients/runtimes. But I will move it into schemas so we can complete this.

[chadrik]

Sure, makes sense.

[jonnor]

flowtrace stuff now in schemas, https://github.com/flowbased/fbp-protocol/blob/master/schema/yaml/trace.yml