Synchronising HSDS and HSDA documentation generation

[timgdavies]

At the moment HSDS is defined via a datapackage.json document.

The HSDA API uses JSON Schema for definitions, manually created from HSDS.

We want to move towards a situation in which:

• One of these is the Single Source of Truth (SSOT) for defining all HSDS / HSDA elements;
• The other one is generated from the SSOT

We also want to ideally be able to display both the HSDA OpenAPI, and HSDS documentation in the same sphinx build.

Tagging @Bjwebb as this is something we could look at as part of some co-working in London in November, and our thinking about documentation generation.

[timgdavies]

In the include-api-branch we have now integrated the api-specification as a sub-module, and added a full HSDA section, so that the docs can be authoritative for HSDA.

This pulls in the master branch of the api-specification, and does not yet test that the YAML definitions for payload in the API specification correctly match the HSDS schema definitions, so it's just a start of addressing this issue overall.

So to track progress of what's done and what remains to do:

• [x] HSDS and HSDA docs built through the same documentation site;
• [ ] HSDA field definitions generated from HSDS;
• [ ] HSDS and HSDA versioning aligned;

For the next steps (aligning definitions) we should consider moving to a new SSOT to generate both, rather than trying to generate HSDA from the current HSDS datapackage.json.

[greggish]

Great. @timgdavies thank you! Do you think that's a near-term action, or something to defer to v2.0?

[mrshll1001]

Closing as we do this now, as of 3.0 :-)