Update schema documentation production to current Metaschema model

[wendellpiez]

User Story:

With usnistgov/metaschema#39 and #12, Metaschema has new features including support for constraints definition.

It has also changed somewhat in its design since the docs production pipeline was built, for example supporting local declarations and homonymy (same name for different thing in different contexts).

Both of these require extension of the Metaschema documentation pipelines to describe these features (as applied in a metaschema) in a legible way for users.

Goals:

More complete, more legible documentation of Metaschema models from the documentation-generation pipelines, both XML and JSON-oriented.

Dependencies:

The new Metaschema design should be feature-complete and stable before we take on the docs.

This will require some (front-end) design as well as work reworking the pipelines.

Acceptance Criteria

• All website and readme documentation affected by the changes in this issue have been updated. Changes to the website can be made in the docs/content directory of your branch.
• A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.

[wendellpiez]

Update Nov 5 2020

XML docs refactoring proceeds well. Ready for closer review, then Hugo integration, while we come back to the JSON docs.

[wendellpiez]

Should have mentioned the working branch is here: https://github.com/wendellpiez/metaschema/tree/issue48-m4-schemadocs

[wendellpiez]

Update Nov 19 2020

The new production XSLTs are now integrated into Hugo to produce a running site, although I need help from @david-waltermire-nist on a couple of points (git alignment; correctly amending the CSS) before able to push a PR with this. Then much work will remain building this out.

[david-waltermire]

This should be updated based on the changes summarized in usnistgov/metaschema#195.

[wendellpiez]

Docs production to be factored out. As it stands this aspect of docs production is functional and adequate (afaik). If not, please make a new Issue.

[aj-stein-nist]

There is however a lot of work on how this current document generation pipeline is used in OSCAL, not here, and there are at least two issues queued up for the current OSCAL sprint, and it is complicated by the fact this work is used in the Metaschema repository for OSCAL, but not generating Metaschema docs for this project itself.

So, may I respectfully requested we talk about this before it is closed? (I see the closeable tag added.) Thanks!

[david-waltermire]

@aj-stein-nist We should talk about this. Let's keep this open for now to allow for your larger questions to be addressed.