Update Respec Documentation

[BenjaminMoe]

This PR updates the documentation for readability.

• Credentials were split off into their own section
• Example documents were moved to their credential definition
• Workflow was changed to link to credentials
• Link to API spec is included in Section 1
• Reference images appear with the document they support

[nissimsan]

Absolutely beautiful!!

[nissimsan]

@BenjaminMoe, should packages/traceability-schemas/scripts/descriptions.json ideally be placed somewhere under docs/ instead. It really is mostly "business content", linking schemas with examples, both of which are also under /docs.
This is minor, let's get it merged and move it later.

[OR13]

The descriptions stuff feels like in belongs in the yaml.

[nissimsan]

@OR13, no I think that description file is something different. It ties schemas to a picture of an old fashioned paper form or example. I suppose we could include such a link on the schema, but we'd have to invent a dedicated tag for it. And I also find it a bit too backwards-oriented with a formal link from schema to such images (it's what we are working to get away from after all).
But, @BenjaminMoe, if the name "descriptions" may me misleading too. If moving into docs, we might wanna rename to something like image-examples.json?

[OR13]

@nissimsan we control all attributes defined in $linkedData... we can add images and alt text to them if we want to... we could consider adding a markdown compatible field, or treating description as markdown.. which is what OAS does currently.

https://swagger.io/specification/

Throughout the specification description fields are noted as supporting CommonMark markdown formatting. Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.

[BenjaminMoe]

The descriptions.json file is a patch. It seems like the easiest way to get the desired effect without making any major changes. We can move the references images to the schema files and find an alternative in a later PR. I can make an issue if needed.

[BenjaminMoe]

Created #357 to address descriptions.json.

[BenjaminMoe]

This PR has been replaced by #364 which takes a more restrained approach to updating the Respec document. Closing.