1068 context docs generation

[kriswest]

resolves #1068
supersedes #1151 contributed by @TheJuanAndOnly99 (moved to the FINOS repo for collaboration)

Generates Context documentation pages from the schema files, so they can be considered a single source of truth and we can stop double maintaining the docs and schemas.

Local preview path (run npm run start in /website): http://localhost:3000/docs/next/context/ref/Action
Netlify preview path: https://deploy-preview-1252--fdc3.netlify.app/docs/next/context/ref/Action

To Do list

Integration into project

• Relies on netlify to run the generation currently which is not good for local development and previews
  • switch that to lifecycle tasks in /website/package.json so that builds and previews run the schema2markdown.js generation script (prebuild and prestart tasks)
• Currently generates docs for all standard versions using the current schemas, except unreleased...
  • Do not generate docs for past standard versions, only for the current draft (unreleased) - allow the versioning system to take care of copying that to a versioned-docs - if we need to fix something in a past version we can do so manually!
• No Overview page for Context Data Part
  • Script is currently generating a new section, it should reuse the old section which contains the overview page. PR should delete all the existing reference pages (we can compare against current site in future

Generated content

• No Context page for Context Data Part
  • As discussed, we should just move this into the overview as no one should be broadcasting that base schema.
• ‘Required’ boolean field is missing for all properties
  • Needs fixing
• Schema link goes to github.com instead of fdc3.finos.org, assume that will update on publish/deploy
  • We could/should use whats in the $id field for this rather than the file URL (will need a code change and we don't need to wait for publishing). However, @mistryvinay and I are not sure it matters... Easier to raise a PR to change it with the github URL.
• All reference links are broken in the Netlify preview, is this expected?
  • Bug: URL is missing the /schemas/ element
• All properties with array types no longer have specific array type (like Instrument[]), they just say ‘array’. Many do have a sentence that says what kind of array it is, and some have reference links to the schema page for the thing it is an array of
  • Bug: need to add details for the items (which is expressed in the schemas). Some will be base types, others references to other schemas.
• Properties with a reference link to another docs page no longer have ‘type’ explicitly declared, this is probably fine as the information is present in the page linked
  • Change the 'Reference' label to 'Type:'
• I find the new format a little difficult to read, I think some indentation for the data under each property would go a long way.
  • Add indentation to properties

Page specific differences

• Chart
  • Instruments property used to have type ‘Instrument[]’ now it has ‘array, is clear from the description that this is an array of instruments
    • Would be fixed by rendering types for arrays
• ChatInitSettings: Message property used to be of type ‘Message’, new one has an example but should probably have a reference link to fdc3.message
  • Properties defined with anyOf and oneOf are not being rendered - and probably won't be popular with @bingenito
• Chat Search Criteria: Properties property used to have type (Instrument | Contact | Organization | string)[] , now it just has type ‘array’
  • Will be fixed by types for arrays and support for anyOf/oneOf
• Instrument
  • ‘id’ subproperties used have working links under ‘More Info’, now they have URLs that aren’t active hyperlinks links displayed like https://www.isin.org/
    • Links are being rendered with backticks around them so they appear to be code instead of hrefs - just remove the backticks! Also include the title as this is often a useful intro to the description.
• Order
  • Details.product has type and description ‘undefined’
    • Sub-properties need to render references to other schemas and skip the title and description if not present as its handled on that page
• OrderList
  • ‘orders’ property used to be of type ‘Trade[]’ which I believe is incorrect, I think it should be Order[], now it just has type ‘array’ but does not have a reference link to the order schema page
  • Generation will fix this - it was a mistake in the old docs page (bad Kris)
• TransactionResult
  • Missing ‘message’ property
    • This is a straight error in the schema - I'll open a PR to fix this now! Good spot @hughtroeger
    • Correcting a syntax error in the TransactionResult Schema #1251

[kriswest]

@hughtroeger and @finos/fdc3-maintainers I've reworked the rendering of the schemas significantly and believe I've dealt with all the current comments. The pages are a lot more readable and properties now render recursively so we catch all the sub properties, array times types etc..

Could you give this another review please!

Local preview path (run npm run start in /website): http://localhost:3000/docs/next/context/ref/Action
Netlify preview path: https://deploy-preview-1252--fdc3.netlify.app/docs/next/context/ref/Action

[hughtroeger]

New UI looks great! Big improvement. Only issue I see is that a number of context types are still missing name and/or id when I compare the preview to the current version of the site.

contact missing name
contactList missing id, name
country missing name
instrument missing name
instrumentList missing name, id
ordersList missing id, name
organization missing name
portfolio missing id, name
position missing id, name
tradeList missing id, name

[kriswest]

@hughtroeger You are correct that id and name are still missing in a number of schemas. I believe this separate PR will fix those: #1233 - its currently blocked on a CLA check for the contributor (which mentioned to @robmoffat at the maintainers meeting, in case FINOS can help there). Given that separate PR are you happy to approve this one?

[kriswest]

P.S. @hughtroeger I checked and don't think I can have the properties expanded by default - docusaurus just replaces the data attribute that controls it. Hence, We'd either have to write a custom MDX component to replace it or drop some script into the page to hack it.

I tend to think quicker access to the example at the bottom of each page is a benefit anyway, you can then drill into individual field detail as needed by opening the collapses.

[hughtroeger]

@kriswest thanks for looking, yeah I think it's totally fine starting collapsed. And yes given that other PR I can definitely approve.

The base branch was changed.