Update sdr schemagen process to extract help into userDoc fields in s…

…chema.usda (Internal change: 2340777)
ld-kerley · Sep 13, 2024 · 1a85ea7 · 1a85ea7
1 parent 4d9afec
commit 1a85ea7
Show file tree

Hide file tree

Showing 7 changed files with 112 additions and 35 deletions.
diff --git a/pxr/usd/usdUtils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/duplicateProp.usda b/pxr/usd/usdUtils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/duplicateProp.usda
@@ -11,11 +11,16 @@ class "TestDuplicatePropsAPI" (
     uniform token inputs:colorMapGamma (
         allowedTokens = ["texture"]
         connectability = "interfaceOnly"
-        displayGroup = "Basic"
-        displayName = "Map Gamma"
-        doc = """
+        customData = {
+            string userDoc = """
+                uniform color mapping for gamma.
+                """
+            string userDocBrief = """
                 uniform color mapping for gamma.
                 """
+        }
+        displayGroup = "Basic"
+        displayName = "Map Gamma"
     )
     color3f outputs:resultRGB
 }

diff --git a/...Utils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/duplicatePropTypeMisMatch.usda b/...Utils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/duplicatePropTypeMisMatch.usda
@@ -11,11 +11,16 @@ class "TestDuplicatePropsAPI" (
     uniform token inputs:colorMapGamma (
         allowedTokens = ["texture"]
         connectability = "interfaceOnly"
-        displayGroup = "Basic"
-        displayName = "Map Gamma"
-        doc = """
+        customData = {
+            string userDoc = """
+                uniform color mapping for gamma.
+                """
+            string userDocBrief = """
                 uniform color mapping for gamma.
                 """
+        }
+        displayGroup = "Basic"
+        displayName = "Map Gamma"
     )
     color3f outputs:resultRGB
 }

diff --git a/...tils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/resultAPIIdentifierMissing.usda b/...tils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/resultAPIIdentifierMissing.usda
@@ -10,11 +10,16 @@ class "APIIdentifierMissingAPI" (
 {
     float inputs:intensity = 1 (
         connectability = "interfaceOnly"
-        displayGroup = "Basic"
-        displayName = "Intensity"
-        doc = """
+        customData = {
+            string userDoc = """
+                intensity: Itensity of the flame thrower.
+                """
+            string userDocBrief = """
                 intensity: Itensity of the flame thrower.
                 """
+        }
+        displayGroup = "Basic"
+        displayName = "Intensity"
     )
     color3f outputs:resultRGB
 }

diff --git a/pxr/usd/usdUtils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/resultAPISchema.usda b/pxr/usd/usdUtils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/resultAPISchema.usda
@@ -12,19 +12,29 @@ class "TestSchemaAPI" (
     uniform token inputs:colorMapGamma (
         allowedTokens = ["texture"]
         connectability = "interfaceOnly"
-        displayGroup = "Basic"
-        displayName = "Map Gamma"
-        doc = """
+        customData = {
+            string userDoc = """
+                uniform color mapping for gamma.
+                """
+            string userDocBrief = """
                 uniform color mapping for gamma.
                 """
+        }
+        displayGroup = "Basic"
+        displayName = "Map Gamma"
     )
     float inputs:intensity = 1 (
         connectability = "interfaceOnly"
-        displayGroup = "Basic"
-        displayName = "Intensity"
-        doc = """
+        customData = {
+            string userDoc = """
+                intensity: Itensity of the flame thrower.
+                """
+            string userDocBrief = """
                 intensity: Itensity of the flame thrower.
                 """
+        }
+        displayGroup = "Basic"
+        displayName = "Intensity"
     )
     int inputs:intNotBool = 0
     color3f outputs:resultRGB

diff --git a/pxr/usd/usdUtils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/result_override.usda b/pxr/usd/usdUtils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/result_override.usda
@@ -39,19 +39,29 @@ class "TestSchemaAPI" (
     uniform token inputs:colorMapGamma (
         allowedTokens = ["texture"]
         connectability = "interfaceOnly"
-        displayGroup = "Basic"
-        displayName = "Map Gamma"
-        doc = """
+        customData = {
+            string userDoc = """
                 uniform color mapping for gamma.
                 """
+            string userDocBrief = """
+                uniform color mapping for gamma.
+                """
+        }
+        displayGroup = "Basic"
+        displayName = "Map Gamma"
     )
     float inputs:intensity = 1 (
         connectability = "interfaceOnly"
-        displayGroup = "Basic"
-        displayName = "Intensity"
-        doc = """
+        customData = {
+            string userDoc = """
                 intensity: Itensity of the flame thrower.
                 """
+            string userDocBrief = """
+                intensity: Itensity of the flame thrower.
+                """
+        }
+        displayGroup = "Basic"
+        displayName = "Intensity"
     )
     int inputs:intNotBool = 0
     color3f outputs:resultRGB

diff --git a/pxr/usd/usdUtils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/schemaConcrete.usda b/pxr/usd/usdUtils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/schemaConcrete.usda
@@ -9,9 +9,8 @@ class TestSchemaConcrete "TestSchemaConcrete" (
 {
     float inputs:exposure = 0 (
         connectability = "interfaceOnly"
-        displayGroup = "Basic"
-        displayName = "Exposure"
-        doc = """
+        customData = {
+            string userDoc = """
               exposure:  Specify the intensity of the light source as a power of 2 (in stops).
               Increasing the exposure by 1 will double the energy emitted by the light source.
               A value of 0 produces an intensity of 1, -1 produces .5. You may wonder why you
@@ -20,25 +19,43 @@ class TestSchemaConcrete "TestSchemaConcrete" (
               number for equivalent Intensity. This is also comfortable to artists familiar with
               photographic measurements.
                 """
+            string userDocBrief = """
+              exposure:  Specify the intensity of the light source as a power of 2 (in stops)."""
+        }
+        displayGroup = "Basic"
+        displayName = "Exposure"
     )
     float inputs:intensity = 1 (
         connectability = "interfaceOnly"
-        displayGroup = "Basic"
-        displayName = "Intensity"
-        doc = """
+        customData = {
+            string userDoc = """
+              intensity: Scales the contribution of this light linearly.
+                """
+            string userDocBrief = """
               intensity: Scales the contribution of this light linearly.
                 """
+        }
+        displayGroup = "Basic"
+        displayName = "Intensity"
     )
     vector3f inputs:sunDirection = (0, 1, 0) (
         connectability = "interfaceOnly"
-        displayGroup = "Basic"
-        displayName = "Direction"
-        doc = """
+        customData = {
+            string userDoc = """
               sunDirection: The *apparent* direction towards the center of
               the sun.  The zenith is at +Y (for noon light) and the
               horizon is in the XZ plane (for sunrise/set).  Note that the
               Y component must non-negative.  Ignored if a month is given.
                 """
+            string userDocBrief = """
+              sunDirection: The *apparent* direction towards the center of
+              the sun.  The zenith is at +Y (for noon light) and the
+              horizon is in the XZ plane (for sunrise/set).  Note that the
+              Y component must non-negative.  Ignored if a month is given.
+                """
+        }
+        displayGroup = "Basic"
+        displayName = "Direction"
     )
     float propNS:testShaderPropWithNS = 0
 }

diff --git a/pxr/usd/usdUtils/updateSchemaWithSdrNode.py b/pxr/usd/usdUtils/updateSchemaWithSdrNode.py
@@ -43,6 +43,11 @@ class PropertyDefiningKeys(ConstantsGroup):
     USD_VARIABILITY = "usdVariability"
     WIDGET = "widget"
 
+class UserDocConstants(ConstantsGroup):
+    USERDOC_FULL = "userDoc"
+    USERDOC_BRIEF = "userDocBrief"
+    MAX_LENGTH_FOR_BRIEF = 500
+
 def _IsNSPrefixConnectableAPICompliant(nsPrefix):
     return (nsPrefix == UsdShade.Tokens.inputs[:1] or \
             nsPrefix == UsdShade.Tokens.outputs[:1])
@@ -122,9 +127,9 @@ def _CreateAttrSpecFromNodeAttribute(primSpec, prop, primDefForAttrPruning,
             attrSpec.hidden = True
 
     if prop.GetHelp():
-        attrSpec.documentation = prop.GetHelp()
+        _SetSchemaUserDocFields(attrSpec, prop.GetHelp())
     elif prop.GetLabel(): # fallback documentation can be label
-        attrSpec.documentation = prop.GetLabel()
+        _SetSchemaUserDocFields(attrSpec, prop.GetLabel())
     if prop.GetPage():
         attrSpec.displayGroup = prop.GetPage()
     if prop.GetLabel():
@@ -166,6 +171,26 @@ def _CreateAttrSpecFromNodeAttribute(primSpec, prop, primDefForAttrPruning,
         attrSpec.SetInfo(PropertyDefiningKeys.CONNECTABILITY, 
                 UsdShade.Tokens.interfaceOnly)
 
+def _SetSchemaUserDocFields(spec, doc):
+    """
+    Sets the user doc custom metadata fields in the generated schema for prim 
+    and attribute specs. 
+    """
+    # Set the "brief" user doc, used for in-context help, e.g. in DCC tools.
+    # If the doc string exceeds a certain length, just use the first sentence.
+    workDoc = ""
+    if len(doc) > UserDocConstants.MAX_LENGTH_FOR_BRIEF:
+        workDoc = doc.partition('.')[0] + '.'
+        # If '.' wasn't found, workDoc will be the entire doc string, so 
+        # instead use the first MAX_LENGTH_FOR_BRIEF chars and append '...'
+        if len(workDoc) > UserDocConstants.MAX_LENGTH_FOR_BRIEF:
+            workDoc = workDoc[:UserDocConstants.MAX_LENGTH_FOR_BRIEF] + "..."
+    else:
+        workDoc = doc
+    spec.customData[UserDocConstants.USERDOC_BRIEF] = workDoc
+    # Set the "long-form" user doc, used when generating HTML schema docs
+    # (example: https://openusd.org/release/user_guides/schemas/index.html)
+    spec.customData[UserDocConstants.USERDOC_FULL] = doc
 
 def UpdateSchemaWithSdrNode(schemaLayer, sdrNode, renderContext="",
         overrideIdentifier=""):
@@ -243,8 +268,8 @@ def UpdateSchemaWithSdrNode(schemaLayer, sdrNode, renderContext="",
         - A "null" value for Widget sdrProperty metadata translates to 
           SdfPropertySpec Hidden metadata.
         - SdrProperty's Help metadata (Label metadata if Help metadata not 
-          provided) translates to SdfPropertySpec's Documentation string 
-          metadata.
+          provided) translates to SdfPropertySpec's userDocBrief and userDoc
+          custom metadata strings.  
         - SdrProperty's Page metadata translates to SdfPropertySpec's
           DisplayGroup metadata.
         - SdrProperty's Label metadata translates to SdfPropertySpec's
@@ -454,7 +479,7 @@ def UpdateSchemaWithSdrNode(schemaLayer, sdrNode, renderContext="",
 
     doc = sdrNode.GetHelp()
     if doc != "":
-        primSpec.documentation = doc
+        _SetSchemaUserDocFields(primSpec, doc)
 
     # gather properties from a prim definition generated by composing apiSchemas
     # provided by apiSchemasForAttrPruning metadata.