Integrate metaschema-produced documentation into Pages site

[wendellpiez]

User Story:

OSCAL end users need up-to-date documentation for the OSCAL models. The Pages redesign is clearly a step forward, but it breaks the current integration with metaschema artifact production, which is now producing markdown files for the old Slate framework. We need this to work so we can dependably produce schema documentation for the site.

Goals:

The new Pages site has up to date XML and JSON schema documentation for the Catalog, Profile, and Implementation models, produced from their respective metaschemas. This also includes documentation for imported models (e.g., metadata module).

Dependencies:

• The new Pages site needs to be up somewhere we can see it (I have a copy running)
• Existing tooling can be reused for this task by altering XSLTs that produce documentation from a metaschema, to fit new (YAML/markdown/HTML) targets
• There is some design work that goes with this including potentially CSS under Pages (tbd). A first version can be plain and simple
• The United States Web Design System framework gives us a place to start see https://designsystem.digital.gov/ for more

Acceptance Criteria

Schema documentation under the new Pages site can be shown to be current and correct to the metaschemas they represent.

Follow-up Work

• Additionally, CI scripts will need to be updated

[anweiss]

Linking #279

[wendellpiez]

Sprint 18 Progress Feb 21 2019

Documentation produced from the catalog schema is now being pushed to a directory for Jekyll, in my branch here: https://github.com/wendellpiez/OSCAL/tree/docs-wip/docs_jekyll_uswds/schemas/_catalog

With help from @howieavp76 I will continue to improve the HTML to his specifications.

% complete: 70%

[howieavp76]

@anweiss @wendellpiez - Sent a PR to Andrew that has the Bootstrap code template. You should be able to use that format in your transform to generate updated HTML that is better organized visually.

[wendellpiez]

Awesome. Very cool. Progress.

I am still concerned however that the nested-list view, and the tabular view, are somewhat redundant.

However, we could also stabilize the output (and the feed) and then worry about further redesign.

[howieavp76]

@wendellpiez - we can refactor and iterate as we go. The formatting looks nice to start and it helps with visual organization. There are a lot of other concepts we can play with such as accordions for collapsing and expanding (since there is a lot of content on one screen).

Will help me to see it all reformatted in a new transform and then we can discuss an improvements list that we can work.

[howieavp76]

Resolved the S3 issue. You can see the updated format at:

OSCAL Staging - Catalog Page

[iMichaela]

02/28/2019

@howieavp76 and @wendellpiez will work on it on Monday, March 4.

[howieavp76]

@wendellpiez - worked with Wendell this AM on the publishing workflow for the XML transformations. Now have this running end to end and updating the site collections to pull from the new location (content->documentation->schemas->oscal-catalog). Working on formatting next and making the USWDS markup match the general template I previously created in Bootstrap.

[howieavp76]

Applied USWDS compliant formatting to replace Bootstrap, fixed labeling issues in CSS, and various minor formatting tweaks to tighten up/minimize the CSS size.

[brian-ruf]

3/7/2019 - Staging site is ready. Capabilities are ready (printing, etc.) Ready to hand-off to team for work on the content.
Andrew has merged Travis' PR. Wendell and Michaela to discuss finished state.
Andrew will create a PR to merge with master.
Two PRs:

1. Replace all Docs sub-directory with new new site, ready for population. (everything needed to produce)
2. New regeneration of content from the metaschema. (actual production)

PR 2 will be merged into NIST Pages.

[david-waltermire]

3/14/2019

Will meet on 3/15/2019 to complete.

[david-waltermire]

3/18/2019

@wendellpiez, @david-waltermire-nist, and @anweiss met on 3/15/2019 to discuss the separate XML and JSON model documentation. @anweiss agreed to frame out the website navigation and @wendellpiez started working on generating the XML and JSON schema docs in Jeckyll, with supervision from @anweiss .

[iMichaela]

3/21/2019

about 90% done. The content review needs to happen on the web page review before considering the issue completed.

[howieavp76]

Latest updates are on AWS

http://nist-oscal.s3-website-us-east-1.amazonaws.com/

[iMichaela]

03/28/2019

This is closed because #314 is taking care of it and #332 is reviewing the pages generated.

[david-waltermire]

04-19-19

One issue remains with the linking of the profile documentation between the XML and JSON versions. Current linking incorrectly points to the catalog pages. @anweiss is fixing this.

[iMichaela]

5/2/2019

waiting for review from @david-waltermire-nist

[brian-ruf]

5/9/2019

@david-waltermire-nist directed us to close this issue.