chore: scaffolding for schema docs

samtranslator/schema/aws_serverless_function.py

@@ -2,7 +2,11 @@
 
 from typing_extensions import Literal
 
-from samtranslator.schema.common import PassThrough, BaseModel, SamIntrinsic
+from samtranslator.schema.common import PassThrough, BaseModel, SamIntrinsic, get_docs_prop
+
+
+def prop(field: str) -> Any:
+    return get_docs_prop("AWS::Serverless::Function.Properties." + field)
 
 
 class ResourcePolicy(BaseModel):
@@ -386,7 +390,7 @@ class Properties(BaseModel):
     AutoPublishAlias: Optional[AutoPublishAlias]
     AutoPublishCodeSha256: Optional[Union[str, SamIntrinsic]]
     CodeSigningConfigArn: Optional[Union[str, SamIntrinsic]]
-    CodeUri: Optional[CodeUriType]
+    CodeUri: Optional[CodeUriType] = prop("CodeUri")
     DeadLetterQueue: Optional[DeadLetterQueueType]
     DeploymentPreference: Optional[DeploymentPreference]
     Description: Optional[Description]
@@ -424,7 +428,7 @@ class Properties(BaseModel):
     Handler: Optional[Handler]
     ImageConfig: Optional[PassThrough]
     ImageUri: Optional[PassThrough]
-    InlineCode: Optional[PassThrough]
+    InlineCode: Optional[PassThrough] = prop("InlineCode")
     KmsKeyArn: Optional[KmsKeyArn]
     Layers: Optional[Layers]
     MemorySize: Optional[MemorySize]

samtranslator/schema/common.py

@@ -1,7 +1,9 @@
+from pathlib import Path
 from typing import Any, Dict, Optional
 
 import pydantic
-from pydantic import Extra
+from pydantic import Extra, Field
+import yaml
 
 # Value passed directly to CloudFormation; not used by SAM
 PassThrough = Any  # TODO: Make it behave like typescript's unknown
@@ -14,12 +16,19 @@
 
 LenientBaseModel = pydantic.BaseModel
 
+_DOCS = yaml.safe_load(Path("samtranslator", "schema", "docs.yaml").read_bytes())
 
-class BaseModel(LenientBaseModel):
-    """
-    By default strict
-    https://pydantic-docs.helpmanual.io/usage/model_config/#change-behaviour-globally
-    """
 
+def get_docs_prop(field: str) -> Any:
+    docs = _DOCS["docs"]["properties"][field]
+    return Field(
+        description=docs,
+        # https://code.visualstudio.com/docs/languages/json#_use-rich-formatting-in-hovers
+        markdownDescription=docs,
+    )
+
+
+# By default strict: https://pydantic-docs.helpmanual.io/usage/model_config/#change-behaviour-globally
+class BaseModel(LenientBaseModel):
     class Config:
         extra = Extra.forbid

samtranslator/schema/docs.yaml

@@ -0,0 +1,19 @@
+docs:
+  properties:
+    AWS::Serverless::Function.Properties.CodeUri: |
+      `CodeUri`   <a name="sam-function-codeuri"></a>
+      The function code's Amazon S3 URI, path to local folder, or [FunctionCode](sam-property-function-functioncode.md) object\. This property only applies if the `PackageType` property is set to `Zip`, otherwise it is ignored\.
+      **Notes**:
+      1\. If the `PackageType` property is set to `Zip` \(default\), then one of `CodeUri` or `InlineCode` is required\.
+      2\. If an Amazon S3 URI or [FunctionCode](sam-property-function-functioncode.md) object is provided, the Amazon S3 object referenced must be a valid [Lambda deployment package](https://docs.aws.amazon.com/lambda/latest/dg/deployment-package-v2.html)\.
+      3\. If the path to a local folder is provided, for the code to be transformed properly the template must go through the workflow that includes [sam build](sam-cli-command-reference-sam-build.md) followed by either [sam deploy](sam-cli-command-reference-sam-deploy.md) or [sam package](sam-cli-command-reference-sam-package.md)\. By default, relative paths are resolved with respect to the AWS SAM template's location\.
+      *Type*: String \| [FunctionCode](sam-property-function-functioncode.md)
+      *Required*: Conditional
+      *AWS CloudFormation compatibility*: This property is similar to the `[Code](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-code)` property of an `AWS::Lambda::Function` resource\. The nested Amazon S3 properties are named differently\.
+    AWS::Serverless::Function.Properties.InlineCode: |
+      `InlineCode`   <a name="sam-function-inlinecode"></a>
+      The Lambda function code that is written directly in the template\. This property only applies if the `PackageType` property is set to `Zip`, otherwise it is ignored\.
+      If the `PackageType` property is set to `Zip` \(default\), then one of `CodeUri` or `InlineCode` is required\.
+      *Type*: String  
+      *Required*: Conditional  
+      *AWS CloudFormation compatibility*: This property is passed directly to the `[ZipFile](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-code.html#cfn-lambda-function-code-zipfile)` property of the `AWS::Lambda::Function` `Code` data type\.