ga4gh-beacon
Markdown updates for 1.1.0
As per request. Instead of copy-pasting from beacon.yaml I chose to update only the fields, and add new keys. Although, if you want consistency, I suggest writing examples to the former file and then copypasting the examples to the markdown file.
I strongly recommend abandoning double documentation, it is extra work to keep two separate documentation files in sync.
WDYT @juhtornr? Is there any reason to explain the fields, endpoints, parameters, etc, again in beacon.md? Because I agree with @teemukataja: it's annoying to maintain this file.
I suggest:
- removing the description of the endpoints, parameters and objects as this information is already in the YAML file.
- keeping the rest of the document (e.g. design principles, security, errors, ...) as this is not in the YAML
- keeping the examples of requests and responses
Markdown from YAML?! We generate the whole set of SchemaBlocks examples and .md ... from the YAML file through a simple Perl script. E.g.
- https://github.com/ga4gh-schemablocks/blocks/blob/master/src/yaml/variant.yaml
leads to
- https://schemablocks.org/schemas/blocks/Variant.html (the HTML is created by Github Jekyll from a .md w/ YAML header)
- https://github.com/ga4gh-schemablocks/blocks/blob/master/doc/markdown/%2Bgenerated__Variant.md
- files in https://github.com/ga4gh-schemablocks/blocks/tree/master/examples/json
Sorry in case I misunderstood the problem ...
This is very convenient for the .md files! (not so sure for the examples because we are currently showing real examples from a Beacon implementation, not theoretical examples) We should definitely explore implementing this in next release (v1.1.1 or v1.2).
@sdelatorrep Is there a planned transition to JSON Schema? Since we'll do the same for SchemaBlocks (documentation from schema using some "standard tooling" - ask @relequestal... - && doc for website as now.
WDYT @juhtornr? Is there any reason to explain the fields, endpoints, parameters, etc, again in beacon.md? Because I agree with @teemukataja: it's annoying to maintain this file.
I suggest:
- removing the description of the endpoints, parameters and objects as this information is already in the YAML file.
- keeping the rest of the document (e.g. design principles, security, errors, ...) as this is not in the YAML
- keeping the examples of requests and responses
I think that it doesn't make sense to keep the same information in two different places. We should have just one place where the information is so therefore I agree with your proposal.
Hi @teemukataja, good work but I spotted several things to fix:
* the title still says v1.0.0
Title now says v1.1.0
* In "Beacon object", the example for `apiVersion` still says `v1.0.0` (not sure if it's necessary to update it as it's just an example, though).
No longer applicable, as objects were removed.
* in `BeaconAlleleResponse` the field `beaconHandover` is missing.
Added.
* in `BeaconDatasetAlleleResponse` there is a field `beaconHandover` but it should be `datasetHandover`.
No longer applicable, as objects were removed.
* the examples you pasted do not have these new fields `beaconHandover` or `datasetHandover`.
Added missing fields.
* definition of ADA-M object has not been updated. In the table where `adamDataUse` is listed, we should add a link to the [repository](https://raw.githubusercontent.com/ga4gh/ADA-M/v1.0.1/adam.yaml) as we do with `consentCodeDataUse` field, and remove the section "Adam Data Use object".
No longer applicable, as objects were removed.
WDYT @juhtornr? Is there any reason to explain the fields, endpoints, parameters, etc, again in beacon.md? Because I agree with @teemukataja: it's annoying to maintain this file.
I suggest:
* removing the description of the endpoints, parameters and objects as this information is already in the YAML file.
Removed
* keeping the rest of the document (e.g. design principles, security, errors, ...) as this is not in the YAML
Kept these.
* keeping the examples of requests and responses
Kept these. (Although Swagger displays responses as well, but not the requests. Would be nice to remove these as well and only keep example requests maybe?)