From 1a85ea7262b387a893271101069cc1fef87b838c Mon Sep 17 00:00:00 2001 From: pixar-oss Date: Fri, 13 Sep 2024 10:59:21 -0700 Subject: [PATCH] Update sdr schemagen process to extract help into userDoc fields in schema.usda (Internal change: 2340777) --- .../baseline/duplicateProp.usda | 11 ++++-- .../baseline/duplicatePropTypeMisMatch.usda | 11 ++++-- .../baseline/resultAPIIdentifierMissing.usda | 11 ++++-- .../baseline/resultAPISchema.usda | 22 ++++++++---- .../baseline/result_override.usda | 22 ++++++++---- .../baseline/schemaConcrete.usda | 35 ++++++++++++++----- pxr/usd/usdUtils/updateSchemaWithSdrNode.py | 35 ++++++++++++++++--- 7 files changed, 112 insertions(+), 35 deletions(-) diff --git a/pxr/usd/usdUtils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/duplicateProp.usda b/pxr/usd/usdUtils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/duplicateProp.usda index 64f9a401a2..67cd9dc28c 100644 --- 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/pxr/usd/usdUtils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/duplicatePropTypeMisMatch.usda b/pxr/usd/usdUtils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/duplicatePropTypeMisMatch.usda index 64f9a401a2..67cd9dc28c 100644 --- a/pxr/usd/usdUtils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/duplicatePropTypeMisMatch.usda +++ b/pxr/usd/usdUtils/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/pxr/usd/usdUtils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/resultAPIIdentifierMissing.usda b/pxr/usd/usdUtils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/resultAPIIdentifierMissing.usda index a3fa20b81f..bc5a62d8ba 100644 --- a/pxr/usd/usdUtils/testenv/testUsdUtilsUpdateSchemaWithSdrNode/baseline/resultAPIIdentifierMissing.usda +++ b/pxr/usd/usdUtils/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 index 55500df64f..fca5dff77e 100644 --- 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 index 9a2e18c43f..86aa657697 100644 --- 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 index 3eab39782f..5b22e6c0a4 100644 --- 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 index a92d6be024..2ed04141fb 100644 --- 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.