Add description for nativeapp and default values

src/snowflake/cli/_app/dev/docs/project_definition_generate_json_schema.py

@@ -30,6 +30,7 @@ class ProjectDefinitionProperty:
  title: str
  indents: int
  item_index: int
+ default: str
  required: bool
  name: str
  description: str
@@ -98,8 +99,11 @@ def _get_definition_sections(
 
  new_property = ProjectDefinitionProperty(
  path=property_name,
- title=property_model.get("title", ""),
- description=property_model.get("description", ""),
+ title=property_model.get("title", "").strip().replace("\n", " "),
+ description=property_model.get("description", "")
+ .strip()
+ .replace("\n", " "),
+ default=property_model.get("default", ""),
  indents=0,
  item_index=0,
  required=is_required,
@@ -152,8 +156,11 @@ def _get_section_properties(
  )
  new_property = ProjectDefinitionProperty(
  path=new_current_path,
- title=property_model.get("title", ""),
- description=property_model.get("description", ""),
+ title=property_model.get("title", "").strip().replace("\n", " "),
+ description=property_model.get("description", "")
+ .strip()
+ .replace("\n", " "),
+ default=property_model.get("default", ""),
  indents=depth,
  item_index=item_index,
  required=is_required,

src/snowflake/cli/_app/dev/docs/templates/definition_description.rst.jinja2

@@ -25,7 +25,9 @@ The following table describes the project definition properties.
  * - **{{property["path"]}}**
 
  *{{"Required" if property["required"] else "Optional"}}*{{ (", *"+property["types"]+"*") if property["types"]}}
-
+{% if property["default"] %}
+ Default: `{{ property["default"] }}`
+{% else %}{% endif %}
  - {{property["title"]}}
 {% if property["description"] %}
  {{ property["description"] }}

src/snowflake/cli/api/project/schemas/native_app/application.py

@@ -17,6 +17,7 @@
 from typing import List, Optional
 
 from pydantic import Field
+from snowflake.cli.api.project.schemas.references import NativeAppReference
 from snowflake.cli.api.project.schemas.updatable_model import (
  IdentifierField,
  UpdatableModel,
@@ -34,14 +35,27 @@ class SqlScriptHookType(UpdatableModel):
 class Application(UpdatableModel):
  role: Optional[str] = Field(
  title="Role to use when creating the application object and consumer-side objects",
+ description=f"""If you do not specify a role, Snowflake CLI attempts to use the default role assigned to your
+ user in your Snowflake account. Typically, you specify this value in the snowflake.local.yml as described in
+ {NativeAppReference.PROJECT_DEFINITION_OVERRIDES.value.get_link_text()}.
+ """,
  default=None,
  )
  name: Optional[str] = Field(
  title="Name of the application object created when you run the snow app run command",
+ description=f"""Based on your platform, Snowflake CLI uses the $USER, $USERNAME, or $LOGNAME environment
+ variables. As with native_app.name, both unquoted and quoted identifiers are supported.
+ Typically, you specify this value in the snowflake.local.yml as described in
+ {NativeAppReference.PROJECT_DEFINITION_OVERRIDES.value.get_link_text()}.
+ """,
  default=None,
  )
  warehouse: Optional[str] = IdentifierField(
  title="Name of the application object created when you run the snow app run command",
+ description=f"""If you do not specify a warehouse, Snowflake CLI attempts to use the default warehouse assigned
+ to your user in your Snowflake account.. Typically, you specify this value in the snowflake.local.yml as
+ described in {NativeAppReference.PROJECT_DEFINITION_OVERRIDES.value.get_link_text()}.
+ """,
  default=None,
  )
  debug: Optional[bool] = Field(

src/snowflake/cli/api/project/schemas/native_app/native_app.py

@@ -33,31 +33,54 @@
 class NativeApp(UpdatableModel):
  name: str = Field(
  title="Project identifier",
+ description="""
+This name allows Snowflake CLI to detect if an associated application package
+(derived from this name) exists in connected accounts and prevents tooling from interacting with
+unrelated (but identically named) objects in an account, by tagging the application or application
+package as belonging to this project. Both unquoted and quoted identifiers are supported. To use
+quoted identifiers, include the surrounding quotes in the YAML value.
+ """.replace(
+ "\n", ""
+ ),
+ examples=["my_first_nativeapp"],
  )
+
  artifacts: List[Union[PathMapping, str]] = Field(
- title="List of file source and destination pairs to add to the deploy root",
+ title="List of file source and destination pairs to add to the deploy root, as well as an optional Snowpark annotation processor",
  )
+
  bundle_root: Optional[str] = Field(
  title="Folder at the root of your project where artifacts necessary to perform the bundle step are stored.",
  default="output/bundle/",
  )
+
  deploy_root: Optional[str] = Field(
  title="Folder at the root of your project where the bundle step copies the artifacts.",
+ description="Once copied to this location, you can deploy them to a Snowflake stage.",
  default="output/deploy/",
  )
+
  generated_root: Optional[str] = Field(
  title="Subdirectory of the deploy root where files generated by the Snowflake CLI will be written.",
  default="__generated/",
  )
+
  source_stage: Optional[str] = Field(
  title="Identifier of the stage that stores the application artifacts.",
+ description="""
+ The value uses the form <schema_name>.<stage_name>. The stage lives within the Application Package object.
+ You can change the name to avoid name collisions.
+ """,
  default="app_src.stage",
  )
+
  scratch_stage: Optional[str] = Field(
  title="Identifier of the stage that stores temporary scratch data used by the Snowflake CLI.",
  default="app_src.stage_snowflake_cli_scratch",
  )
+
  package: Optional[Package] = Field(title="PackageSchema", default=None)
+
  application: Optional[Application] = Field(title="Application info", default=None)
 
  @field_validator("source_stage")

src/snowflake/cli/api/project/schemas/native_app/package.py

@@ -18,6 +18,8 @@
 
 from pydantic import Field, field_validator, model_validator
 from snowflake.cli.api.project.schemas.native_app.application import PostDeployHook
+from pydantic import Field, field_validator
+from snowflake.cli.api.project.schemas.references import NativeAppReference
 from snowflake.cli.api.project.schemas.updatable_model import (
  IdentifierField,
  UpdatableModel,
@@ -28,21 +30,37 @@
 
 class Package(UpdatableModel):
  scripts: Optional[List[str]] = Field(
- title="List of SQL file paths relative to the project root", default=None
+ title="List of SQL file paths relative to the project root",
+ default=None,
+ description=f"""These files are executed as the provider when you deploy the application package, such as to
+ populate shared content. Note that these files must be idempotent. You can also use Jinja templates in place of
+ SQL files, but currently, the only variable allowed in this file should be named package_name, which will be
+ replaced by native_app.package.name.""",
  )
  role: Optional[str] = IdentifierField(
  title="Role to use when creating the application package and provider-side objects",
+ description=f"""Typically, you specify this value in the snowflake.local.yml as described in
+ {NativeAppReference.PROJECT_DEFINITION_OVERRIDES.value.get_link_text()}.""",
  default=None,
  )
  name: Optional[str] = IdentifierField(
  title="Name of the application package created when you run the snow app run command",
+ description=f"""Based on your platform, Snowflake CLI uses the $USER, $USERNAME, or $LOGNAME environment
+ variables. As with native_app.name, both unquoted and quoted identifiers are supported. Typically,
+ you specify this value in the snowflake.local.yml as described in
+ {NativeAppReference.PROJECT_DEFINITION_OVERRIDES.value.get_link_text()}.""",
  default=None,
  )
  warehouse: Optional[str] = IdentifierField(
- title="Warehouse used to run the scripts", default=None
+ title="Warehouse used to run the scripts provided as part of native_app.package.scripts",
+ description=f"""Typically, you specify this value in the snowflake.local.yml as described in
+ {NativeAppReference.PROJECT_DEFINITION_OVERRIDES.value.get_link_text()}.""",
+ default=None,
  )
  distribution: Optional[DistributionOptions] = Field(
  title="Distribution of the application package created by the Snowflake CLI",
+ description="""When running snow app commands, Snowflake CLI warns you if the application package you are
+ working with has a different value for distribution than is set in your resolved project definition.""",
  default="internal",
  )
  post_deploy: Optional[List[PostDeployHook]] = Field(

src/snowflake/cli/api/project/schemas/native_app/path_mapping.py

@@ -17,6 +17,7 @@
 from typing import Any, Dict, List, Optional, Union
 
 from pydantic import Field, field_validator
+from snowflake.cli.api.project.schemas.references import NativeAppReference
 from snowflake.cli.api.project.schemas.updatable_model import UpdatableModel
 
 
@@ -32,17 +33,26 @@ class ProcessorMapping(UpdatableModel):
 
 class PathMapping(UpdatableModel):
  src: str = Field(
- title="Source path or glob pattern (relative to project root)", default=None
+ title="Source path or glob pattern (relative to project root)",
+ default=None,
+ examples=["app/*", "streamlit/*", "src/resources/images/snowflake.png"],
  )
 
  dest: Optional[str] = Field(
  title="Destination path on stage",
- description="Paths are relative to stage root; paths ending with a slash indicate that the destination is a directory which source files should be copied into.",
+ description="""
+Paths are relative to stage root; paths ending with a slash indicate that the destination is a directory which source files should be copied into.
+ """,
  default=None,
+ examples=["./", "streamlit/", "streamlit/images"],
  )
 
  processors: Optional[List[Union[str, ProcessorMapping]]] = Field(
  title="List of processors to apply to matching source files during bundling.",
+ description=f"""
+Currently, the only value supported is snowpark. For more information about
+custom processing, see {NativeAppReference.AUTOMATIC_SQL_CODE_GENERATION.value.get_link_text()} and
+the {NativeAppReference.SNOW_APP_BUNDLE.value.get_link_text()} command.""",
  default=[],
  )
 

src/snowflake/cli/api/project/schemas/references.py

@@ -0,0 +1,43 @@
+# Copyright (c) 2024 Snowflake Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+@dataclass
+class _ExternalLink:
+ text: str
+ link: str
+
+ def get_link_text(self) -> str:
+ """Returns the name and link in specific format."""
+ return f"`{self.text} <{self.link}>`_"
+
+
+class NativeAppReference(Enum):
+ AUTOMATIC_SQL_CODE_GENERATION = _ExternalLink(
+ text="Automatic SQL code generation",
+ link="https://docs.snowflakze.com/en/developer-guide/snowflake-cli-v2/native-apps/bundle-app#label-cli-nativeapp-bundle-codegen",
+ )
+
+ SNOW_APP_BUNDLE = _ExternalLink(
+ text="snow app bundle",
+ link="https://docs.snowflake.com/en/developer-guide/snowflake-cli-v2/command-reference/native-apps-commands/bundle-app",
+ )
+
+ PROJECT_DEFINITION_OVERRIDES = _ExternalLink(
+ text="Project definition overrides",
+ link="https://docs.snowflake.com/en/developer-guide/snowflake-cli-v2/native-apps/project-definitions#project-definition-overrides",
+ )