EPIC generated schema docs and maps improvements

[wendellpiez]

User Story:

For functionality and usability, we need to address a number of glitches in the documentation (web pages) currently generated for XML and JSON schemas produced from metaschema sources. These include both the model documentation and the model maps.

Goals:

This is an EPIC representing a number of work items relating to the web side and generated schema documentation.

https://github.com/usnistgov/metaschema/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation

This order might make sense

• Create Metaschema schema docs mockup for docs development metaschema#71
• Resolve Syntax Documentation Generation Issues metaschema#113
• Model map enhancement: links to local definitions metaschema#94 (refactoring main page navigation in general)
• Syntax Documentation Improvements #15
• Syntax Map Improvements metaschema#105 OSCAL Model Maps - further enhancements #36 Model Map enhancement: keys to reading #30

Also visit

• empty elements (cf Metaschema enhancements for OSCAL (empty elements) OSCAL#829)
• scrolling issues with menu? OSCAL Documentation page is missing a quick access menu OSCAL#787
• map rendering issues Missing "prose" field in XML Outline OSCAL#847 Misleading or incorrect recursion indicators in XML Format Outline OSCAL#848
• Link Issue in Generated Content for Pages OSCAL#670

Dependencies:

None.

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.

{The items above are general acceptance criteria for all User Stories. Please describe anything else that must be completed for this issue to be considered resolved.}

[wendellpiez]

Pushed draft PR here: usnistgov/metaschema#127

So far we have corrections or improvements addressing usnistgov/OSCAL#847 usnistgov/OSCAL#848 and usnistgov/OSCAL#670.

Next comes a more substantive overhaul of nav/layout for main docs pages, to improve usability and transparency.

[wendellpiez]

Progress report March 25

Several small but tricky issues (mainly with model maps) have been addressed. Remaining issues have to do with linking and navigation. The new pages will each index to names of structures in the format - that is, users will be able to look up the names of elements (in XML) and objects (in JSON) without having to know their metaschema object types in advance. Work on this is underway.

[wendellpiez]

#36 and usnistgov/metaschema#105 are done.

usnistgov/metaschema#94 and #15 could be pushed to usnistgov/metaschema#128, which is a dependency for them.

This leaves usnistgov/OSCAL#787 and #30, both possibly lower priority.

[aj-stein-nist]

This epic combines some bug/feature enhancements for the XSLT implementation and doc generation pipeline, and other issues are about improvements to Metaschema. Split out the epics accordingly to properly prioritize epics and their issues.

[wendellpiez]

This EPIC tracked multiple work items respecting Metaschema docs, which have mainly been addressed as noted.

For remaining Issues it needs either to be moved to M4 implementation stack regarding Documentation Generation, or closed. Since unaddressed Issues are currently being addressed otherwise (including in OSCAL), I suggest closing.

[david-waltermire]

We should discuss the remaining work here and #14 with @aj-stein-nist. It would be good to close this and create a new clean EPIC to outline documentation generation work needed going forward.