Revert 9 docs redesign (#11)

* Feature metaschema d2 next (usnistgov#277) * Patched with changes from feature-metaschema-d2 * Moving testing schema into schema/demo dir for more robust testing of (portable, replicable) metaschema infrastructure * Cleanup and refactoring metaschema production for demo * Patched with changes from feature-metaschema-d2 * Cleanup and refactoring metaschema production for demo * More adjustments and documentation of metaschema * Adjustments to metaschema notes doc * Now supporting namespace assignment per metaschema * Better support for modular metaschemas * Metaschema support for namespaces, acquired (imported) models * Scrubbing old prose modules * Metaschema XML documentation now respecting namespaces in XML artifacts * Minor tweaks to comments * More improvements in view of namespaces. JSON examples not yet working. * Better handling of examples now * Removing unneeded test files * Correcting syntax error * Adjustments in demo metaschema * Added draft metadata to SP800-53 profiles; also new SP800-53 catalog with (draft) metadata. * Adding Markdown-conversion and JSON-handling code * 'Hardening' markdown conversion * Adding placeholder files for new catalog and profile metaschemas with namespace support - nb namespaces assigned have not been changed. But namespace support in the metaschema infrastructure can be tested. * Cleaning up catalog and profile schemas (with namespaces) and examples * Updated demo schema readme * Tighter co-occurrence testing * Docs redesign (#9) * Create Readme.md * Create readme.md * Add files via upload * Add files via upload * Add files via upload * Add files via upload * Add files via upload * Add files via upload * Add files via upload * Delete DesignElements.md * Add files via upload * Update Design Elements.md * Add files via upload * Update Design Elements.md * Update Landing Page.md * Update Landing Page.md * Update Landing Page.md * Update Roadmap.md * Update Roadmap.md * Update Roadmap.md * Update Roadmap.md * Add files via upload * Update Design Elements.md * Update Design Elements.md * Update Case Studies.md * Update Case Studies.md * Update Case Studies.md * Update Case Studies.md * Update Case Studies.md * Update Overview.md * Update Overview.md * Update Landing Page.md * Update Roadmap.md * Update Roadmap.md * Add files via upload * Update Design Elements.md * Update Design Elements.md * Update Design Elements.md * Update Design Elements.md * Update Overview.md * Update Roadmap.md * Update Overview.md * Update Overview.md * Update Overview.md * Add files via upload * Add files via upload * Add files via upload * Delete OSCAL_ContentPage_Sample.png * Update Landing Page.md * Update Landing Page.md * Update Content Page.md * Update Content Page.md * Update Content Page.md * Update Products.md * Update Products.md * Update Products.md * Add files via upload * Update Design Elements.md * Update Case Studies.md * Add files via upload * Delete Products.md * Delete Roadmap.md * Update Design Elements.md * Add files via upload * Add files via upload * Update Landing Page.md * Update Overview.md * Add files via upload * Update Get Involved.md * Update Get Involved.md * Update Get Involved.md * Update Get Involved.md * Update Design Elements.md * Add files via upload * Update Design Elements.md * Update Design Elements.md * Update Design Elements.md * Update Design Elements.md * Delete OSCAL_Logo1.png * Delete OSCAL_Logo2.png * Delete OSCAL_Logo3.png * Delete OSCAL_Logo4.png * Add files via upload * Update Design Elements.md * Delete OSCAL_Logo1.png * Delete OSCAL_Logo2.png * Add files via upload * Delete OSCAL_Logo1.png * Add files via upload * Update Readme.md * Update Get Involved.md * Rename Case Studies.md to Case Study.md * Update Case Study.md * Update Scenario.md * Update Producer.md * Update Producer.md * Update Consumer.md * Update Consumer.md * Update Get Involved.md * Update Producer.md * Update Consumer.md * Update Producer.md * Delete Design Elements.md * Update Get Involved.md * Update Consumer.md * Update Producer.md * Add files via upload * Add files via upload * Update Contact.md * Update Contact.md * Update Consumer.md * Update Producer.md * Update and rename Overview.md to LearnMore.md * Rename LearnMore.md to Learn More.md * Update Contact.md * Update Contact.md * Update Learn More.md * Create Schemas.md * Update Schemas.md * Update Schemas.md * Update Schemas.md * Create Producer Examples.md * Update Schemas.md * Delete Content Page.md * Update and rename Producer Examples.md to Consumer Examples.md * Update Scenario.md * Update Scenario.md * Delete Landing Page.md * Update Learn More.md * Update Learn More.md * Update Learn More.md * Update Learn More.md * Update Learn More.md * Update Learn More.md * Update Learn More.md * Feature metaschema d2 next (usnistgov#277) * Patched with changes from feature-metaschema-d2 * Moving testing schema into schema/demo dir for more robust testing of (portable, replicable) metaschema infrastructure * Cleanup and refactoring metaschema production for demo * Patched with changes from feature-metaschema-d2 * Cleanup and refactoring metaschema production for demo * More adjustments and documentation of metaschema * Adjustments to metaschema notes doc * Now supporting namespace assignment per metaschema * Better support for modular metaschemas * Metaschema support for namespaces, acquired (imported) models * Scrubbing old prose modules * Metaschema XML documentation now respecting namespaces in XML artifacts * Minor tweaks to comments * More improvements in view of namespaces. JSON examples not yet working. * Better handling of examples now * Removing unneeded test files * Correcting syntax error * Adjustments in demo metaschema * Added draft metadata to SP800-53 profiles; also new SP800-53 catalog with (draft) metadata. * Adding Markdown-conversion and JSON-handling code * 'Hardening' markdown conversion * Adding placeholder files for new catalog and profile metaschemas with namespace support - nb namespaces assigned have not been changed. But namespace support in the metaschema infrastructure can be tested. * Cleaning up catalog and profile schemas (with namespaces) and examples * Updated demo schema readme * Tighter co-occurrence testing * docs redesign prototype * add Docker artifacts for dev * volume mount quotes * walkthrough prototype * add walkthrough page * use official nist header and foot * initial refactor based on new site map * site nav prototyping * oscalkit addition * Test * fix sidenav and schema ref * Early version JSON-docs production from metaschema * Removed unwanted namespace declarations from XML samples * Removed unwanted namespace declaration from XML samples * Experiments with serialization of XML literals in JSON from XSLT pipeline * Travis website updates (#3) * Website Updates - Splash Page * fix sidenav and schema ref * Updates based on initial NIST feedback (#4) * relationship page per Wendell (#5) * Setting up metaschema documentation -- HTML feed for Jekyll * Improved serialization on working example * Improved serialization * Now added uswds tables * Now including JSON examples * On XML and JSON examples, now emulating mockup with hooks for Jekyll/uswds CSS and scripting * More enhancements to schema docs * Adding catalog schema docs as HTML fragments * Testing documentation handling * Testing documentation; metaschema Schematron adjustment * Adding YAML header to top level file * Reverting back to safer version * Now including docs for elements included in metaschemas via import from other metaschemas (35 new files) usnistgov#286 usnistgov#314 * Provided descriptive YAML headers to HTML outputs from metaschema docs production for Jekyll integration. * New file set in correct subdirectory for Jekyll * Removing extraneous file left from debugging * Removing diagnostic output from metaschema docs generation * Corrected production of header id for navigation * Providing some simple tagging for syntax coloring over XML literals * Improvements to representation of samples in schema docs, now to use Jekyll syntax highlighting. * Moving the documentation outputs to a path for Jekyll * More corrections to samples serializations * merge split html from metaschema * JSON prettify block * Initial Schema Formatting * css changes * Revert "Docs redesign (#9)" This reverts commit ef1e5a9.
wendellpiez · Mar 5, 2019 · 93f202e · 93f202e
1 parent 8c1bd33
commit 93f202e
Show file tree

Hide file tree

Showing 4 changed files with 169 additions and 3 deletions.
diff --git a/build/metaschema/lib/metaschema-check.sch b/build/metaschema/lib/metaschema-check.sch
@@ -110,9 +110,8 @@
             <sch:assert test="exists(document(@href)/m:METASCHEMA)">Can't find a metaschema at <sch:value-of select="@href"/></sch:assert>
             <!--<sch:report test="empty($imported-schemas/m:METASCHEMA)">Don't see imported schemas</sch:report>-->
         </sch:rule>
-        
+
         <sch:rule context="/m:METASCHEMA/*[matches(@acquire-from,'\S')]"/>
-
         <sch:rule context="m:define-assembly">
             <sch:assert role="warning" test="@name = (//m:assembly/@named | //m:assemblies/@named | /m:METASCHEMA/@root)">Definition for assembly '<sch:value-of select="@name"/>' is not used.</sch:assert>
         </sch:rule>

diff --git a/build/metaschema/xml/produce-and-run-xml-documentor.xsl b/build/metaschema/xml/produce-and-run-xml-documentor.xsl
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    xmlns:xs="http://www.w3.org/2001/XMLSchema"
+    exclude-result-prefixes="xs"
+    xpath-default-namespace="http://csrc.nist.gov/ns/oscal/metaschema/1.0"
+    version="3.0">
+
+    <xsl:output method="text"/>
+
+    <!-- The function fn:transform() returns a map, whose primary results are under 'output'
+         unless a base output URI is given
+         https://www.w3.org/TR/xpath-functions-31/#func-transform -->
+    <xsl:variable name="xslt">
+        <xsl:variable name="runtime"   select="map {
+            'xslt-version'        : 3.0,
+            'stylesheet-location' : 'produce-xml-documentor.xsl',
+            'source-node'         : / }" />
+
+        <xsl:sequence select="transform($runtime)?output"/>
+    </xsl:variable>
+
+    <!-- XPath 3.1 transform() is documented here: https://www.w3.org/TR/xpath-functions-31/#func-transform   -->
+    <xsl:template match="/">
+        <xsl:variable name="xslt-uri" select="resolve-uri((/METASCHEMA/short-name || '-xml-documentor.xsl'))"/>
+        <xsl:variable name="runtime"   select="map {
+            'xslt-version'       : 3.0,
+            'stylesheet-base-uri': $xslt-uri,
+            'stylesheet-node'    : $xslt,
+            'source-node'        : / }" />
+        <xsl:sequence select="transform($runtime)?output"/>
+
+    </xsl:template>
+
+
+</xsl:stylesheet>
diff --git a/build/metaschema/xml/produce-xml-documentor.xsl b/build/metaschema/xml/produce-xml-documentor.xsl
@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    xmlns:xs="http://www.w3.org/2001/XMLSchema"
+    xpath-default-namespace="http://csrc.nist.gov/ns/oscal/metaschema/1.0"
+    version="3.0"
+
+    xmlns:xslt="http://csrc.nist.gov/ns/oscal/metaschema/xslt-alias">
+
+<!-- Purpose: Produce an XSLT supporting production of XML-oriented metaschema documentation pertaining
+        to a particular catalog type.
+        
+        In the XML pipeline this XSLT can be minimal, producing an XSLT that does little but
+        provide for expansion of examples while calling a generic XSLT (also in this subdirectory)
+        to do most of the actual conversion work.
+        
+        NB that outputs must support serialization into JSON, i.e. plain text. -->
+
+<!-- Input:   A Metaschema -->
+<!-- Output:  An XSLT, supporting production of metaschema documentation, in HTML format. -->
+
+<!-- nb A schema and Schematron for the metaschema format should be found nearby. -->
+
+    <xsl:output indent="yes"/>
+    <xsl:strip-space elements="*"/>
+
+    <xsl:namespace-alias stylesheet-prefix="xslt" result-prefix="xsl"/>
+
+    <xsl:variable name="target-namespace" select="string(/METASCHEMA/namespace)"/>
+
+    <xsl:template match="METASCHEMA">
+        <xslt:stylesheet version="3.0"
+            xpath-default-namespace="http://csrc.nist.gov/ns/oscal/metaschema/1.0"
+            exclude-result-prefixes="#all">
+
+
+
+            <xsl:comment> METASCHEMA docs production </xsl:comment>
+
+            <xsl:comment> XHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHX </xsl:comment>
+            <xsl:call-template  name="furniture"/>
+            <xsl:comment> XHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHXXHHX </xsl:comment>
+            <xsl:apply-templates/>
+
+
+        </xslt:stylesheet>
+    </xsl:template>
+
+    <!--<example href="base-example.xml" path="/descendant::single-required-field[1]">
+        <description>An example in a remote document</description>
+    </example>-->
+
+    <!-- XXX This has to go b/c @acquire-from objects won't have examples ... but, do we want em?  -->
+    <!--<xsl:template match="METASCHEMA//*">
+        <xsl:if test="exists(descendant::example)">
+            <xsl:apply-templates/>
+        </xsl:if>
+    </xsl:template>-->
+
+    <xsl:template match="text()"/>
+
+    <xsl:template priority="2" match="example[matches(@href,'\S')][matches(@path,'\S')]">
+        <xslt:template
+            match="example[@href='{ encode-for-uri(@href) }'][@path='{normalize-space(@path)}']" mode="expand-example">
+            <xslt:copy copy-namespaces="no">
+                <xslt:apply-templates select="node() | @*" mode="#current"/>
+                <!-- NB: ns should be dynamic (driven by metaschema) -->
+
+                <xslt:copy-of select="document( resolve-uri(@href,base-uri(.))){@path}" copy-namespaces="no"
+                    xpath-default-namespace="{$target-namespace}"/>
+            </xslt:copy>
+        </xslt:template>
+    </xsl:template>
+
+    <xsl:template name="furniture">
+
+        <xslt:import href="../../../util/publish/XSLT/html-to-markdown.xsl"/>
+        <xslt:import href="../lib/metaschema-xml-html.xsl"/>
+
+        <xslt:variable name="home" select="/"/>
+        <xslt:key name="declarations-by-name"
+            match="define-field | define-assembly | define-flag" use="@name"/>
+
+        <!-- output method must be text for good markdown including unescaped code snips   -->
+        <xslt:output method="text"/>
+
+        <xslt:template priority="5"
+            match="define-assembly[exists(@acquire-from)] |
+            define-field[exists(@acquire-from)] |
+            define-flag[exists(@acquire-from)]"
+            expand-text="true">
+            <xslt:variable name="defining" select="@name"/>
+            <xslt:variable name="module" select="@acquire-from"/>
+            <xslt:variable name="definition"
+                select="/METASCHEMA/import[@name = $module]/key('declarations-by-name', $defining, document(@href, $home))"/>
+            <xslt:apply-templates select="$definition"/>
+            <xslt:if test="empty($definition)">
+               <xsl:comment> No definition found for { $defining } in { $module } at { /METASCHEMA/import[@name=$module]/@href }</xsl:comment>
+                    </xslt:if>
+        </xslt:template>
+
+        <xslt:template match="node() | @*" mode="expand-example">
+            <xslt:copy copy-namespaces="no">
+                <xslt:apply-templates select="node() | @*" mode="#current"/>
+            </xslt:copy>
+        </xslt:template>
+
+        <xslt:variable name="expanded">
+            <xslt:apply-templates mode="expand-example" select="/"/>
+        </xslt:variable>
+
+        <!-- XXX template here to intercept @acquire-from see produce-xsd.xsl           -->
+
+        <xslt:template match="/">
+            <xslt:variable name="html">
+                <xslt:for-each select="$expanded/*">
+                    <html xmlns="http://www.w3.org/1999/xhtml">
+                        <body>
+                            <xslt:apply-templates/>
+                            <!--<xslt:apply-templates select="$imported/key('definitions',$all-references,.)[not(@name=$here-declared/(@name|@named))]"/>-->
+                        </body>
+                    </html>
+
+                </xslt:for-each>
+            </xslt:variable>
+            <!--<xsl:copy-of select="$html"/>-->
+            <xslt:apply-templates select="$html" mode="md"/>
+        </xslt:template>
+
+    </xsl:template>
+
+</xsl:stylesheet>
diff --git a/schema/demo/run-test-metaschema.sh b/schema/demo/run-test-metaschema.sh
@@ -38,7 +38,6 @@ MAKE_JSC="java -jar $SAXON -s:$METASCHEMAXML -o:$JSONDIR/$BASENAME-schema.json -
 CONV_XML="java -jar $SAXON -s:$METASCHEMAXML -o:$CONVERSION_DIR/$BASENAME-xml-converter.xsl -xsl:$LIBDIR/xml/produce-xml-converter.xsl"
 CONV_JSON="java -jar $SAXON -s:$METASCHEMAXML -o:$CONVERSION_DIR/$BASENAME-json-converter.xsl  -xsl:$LIBDIR/json/produce-json-converter.xsl"
 
-
 DOCS_XSLT="java -jar $SAXON -s:$METASCHEMAXML -o:$LIBDIR/temp/$BASENAME-xml-docs-md.xsl -xsl:$LIBDIR/xml/produce-and-run-documentor.xsl"
 
 
@@ -56,6 +55,7 @@ echo _ Made XML-to-JSON converter ______ $CONVERSION_DIR/$BASENAME-xml-converter
 $CONV_JSON
 echo _ Made JSON-to-XML converter ______ $CONVERSION_DIR/$BASENAME-json-converter.xsl
 
+
 $DOCS_XSLT
 echo _ Made Metaschema documentation _ $DOCSDIR/${BASENAME}_xml.md $DOCSDIR/json_${BASENAME}_json.md
 echo