Display deprecation notice in generated documentation (#115)

* Add deprecated definition to everything metaschema * Display deprecation in definition documentation * Display deprecation in reference documentation * Display deprecation in outline documentation * Add CSS styling for deprecated outline items
usnistgov · Mar 29, 2024 · f3722c7 · f3722c7
1 parent 7637dd2
commit f3722c7
Show file tree

Hide file tree

Showing 8 changed files with 35 additions and 8 deletions.
diff --git a/src/document/common/common-definitions.xsl b/src/document/common/common-definitions.xsl
@@ -132,7 +132,7 @@
             <xsl:apply-templates select="." mode="find-definition"/>
         </xsl:variable>
         <div class="model-entry definition { name() }">
-            <div class="{ if ($is-inline) then 'instance-header' else 'definition-header' }">
+            <div class="{ if ($is-inline) then 'instance-header' else 'definition-header' }{ $definition/@deprecated/' deprecated-header' }">
                 <xsl:element namespace="http://www.w3.org/1999/xhtml" name="{ $header-tag }"
                     expand-text="true">
                     <xsl:call-template name="mark-id"/>
@@ -152,6 +152,7 @@
             </div>
             <xsl:where-populated>
                 <div class="body">
+                    <xsl:apply-templates select="$definition/@deprecated"/>
                     <!-- in no mode for regular contents including use-name, group-as etc. -->
 
 <!-- split out to control order; include group-as, json-key etc. etc. from definitions                   -->
@@ -275,6 +276,14 @@
         </p>
     </xsl:template>
 
+    <xsl:template match="@deprecated">
+        <p>
+            <span class="usa-tag">deprecated</span>
+            <xsl:text> as of </xsl:text>
+            <xsl:value-of select="."/>
+        </p>
+    </xsl:template>
+
     <xsl:template match="p">
         <p class="p">
             <xsl:apply-templates/>
@@ -288,4 +297,4 @@
         </xsl:element>
     </xsl:template>
 
-</xsl:stylesheet>
+</xsl:stylesheet>
diff --git a/src/document/common/common-reference.xsl b/src/document/common/common-reference.xsl
@@ -115,6 +115,14 @@
          </p>
       </xsl:where-populated>
    </xsl:template>
+
+   <xsl:template match="@deprecated" mode="produce">
+      <p>
+         <span class="usa-tag">deprecated</span>
+         <xsl:text> as of </xsl:text>
+         <xsl:value-of select="."/>
+     </p>
+   </xsl:template>
 
    <xsl:template match="formal-name" mode="produce">
       <xsl:where-populated>
@@ -308,4 +316,4 @@
    </xsl:template>
 
 
-</xsl:stylesheet>
+</xsl:stylesheet>
diff --git a/src/document/common/hugo-css-emulator.xsl b/src/document/common/hugo-css-emulator.xsl
@@ -259,6 +259,10 @@ span.OM-datatype { font-family: sans-serif;
 
    }
 
+.OM-name-deprecated {
+    text-decoration: line-through;
+  }
+
 .OM-ref {
     @extend .text-primary;
     font-style: normal;

diff --git a/src/document/json/object-map-html.xsl b/src/document/json/object-map-html.xsl
@@ -216,7 +216,7 @@ details:not([open]) .show-closed { display: inline }
       <xsl:if test="empty(@_tree-json-id)">
          <xsl:message expand-text="true">not seeing json tree id for { name(.) }</xsl:message>
       </xsl:if>
-      <a class="OM-name" href="{ $reference-link }#{  @_tree-json-id }">
+      <a class="OM-name{ @deprecated/' OM-name-deprecated' }" href="{ $reference-link }#{  @_tree-json-id }">
          <xsl:value-of select="(@key,@gi,@name)[1]"/>
       </a>
    </xsl:template>

diff --git a/src/document/json/object-reference-html.xsl b/src/document/json/object-reference-html.xsl
@@ -65,7 +65,7 @@
       <div class="model-entry definition { tokenize($me/@_metaschema-json-id,'/')[2] }">
          <xsl:variable name="header-class" expand-text="true">{ if (exists(parent::map)) then
             'definition' else 'instance' }-header</xsl:variable>
-         <div class="{ $header-class }">
+         <div class="{ $header-class }{ $me/@deprecated/' deprecated-header' }">
             <!-- 
                Generate the proper class attribute to match a given HTML header from $header-tag (h1, h2,...h6) 
                to define the proper corresponding style (toc1, toc2,... toc6) as bound by toc{ $level } in Hugo.
@@ -102,6 +102,7 @@
 
          <xsl:where-populated>
             <div class="body">
+               <xsl:apply-templates select="$me/@deprecated" mode="produce" />
                <xsl:apply-templates select="$me/description" mode="produce"/>
                <xsl:call-template name="remarks-group">
                   <xsl:with-param name="these-remarks" select="$me/remarks"/>

diff --git a/src/document/xml/element-map-html.xsl b/src/document/xml/element-map-html.xsl
@@ -81,7 +81,7 @@ div.OM-map p { margin: 0ex }
 
 
    <xsl:template match="*[exists(@_tree-xml-id)]" mode="linked-name">
-      <a class="OM-name" href="{ $reference-link }#{ @_tree-xml-id }">
+      <a class="OM-name{ if (@deprecated) then ' OM-name-deprecated' else ''}" href="{ $reference-link }#{ @_tree-xml-id }">
          <xsl:value-of select="(@gi,@name)[1]"/>
       </a>
    </xsl:template> 

diff --git a/src/document/xml/element-reference-html.xsl b/src/document/xml/element-reference-html.xsl
@@ -64,7 +64,7 @@
       <div class="model-entry definition { tokenize(@_metaschema-xml-id,'/')[2] }">
          <xsl:variable name="header-class" expand-text="true">{ if (exists(parent::map)) then
             'definition' else 'instance' }-header</xsl:variable>
-         <div class="{ $header-class }">
+         <div class="{ $header-class }{ if (exists(@deprecated)) then ' deprecated-header' else '' }">
             <!-- 
                Generate the proper class attribute to match a given HTML header from $header-tag (h1, h2,...h6) 
                to define the proper corresponding style (toc1, toc2,... toc6) as bound by toc{ $level } in Hugo.
@@ -106,6 +106,7 @@
          </div>
          <xsl:where-populated>
             <div class="body">
+               <xsl:apply-templates select="@deprecated" mode="produce" />
                <xsl:apply-templates select="description" mode="produce"/>
                <xsl:apply-templates select="value" mode="produce"/>
                <xsl:call-template name="remarks-group"/>

diff --git a/src/testing/models_metaschema.xml b/src/testing/models_metaschema.xml
@@ -46,6 +46,10 @@
         <root-name>EVERYTHING</root-name>
         <flag ref="id"/>
         <model>
+            <define-flag name="deprecated-flag" deprecated="1.0">
+                <formal-name>Deprecated</formal-name>
+                <description>a deprecated flag.</description>
+            </define-flag>
             <field ref="field-1only"/>
             <field ref="overloaded">
                 <use-name>overloaded1</use-name>
@@ -334,4 +338,4 @@
         </model>
     </define-assembly>
 
-</METASCHEMA>
+</METASCHEMA>