use autodoc-pydantic to improve documentation of pydantic models (#…

…2527)

docs/Makefile

@@ -28,4 +28,4 @@ open:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -j auto
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -j auto --show-traceback

docs/source/conf.py

@@ -48,6 +48,7 @@
     "sphinx_design",
     "sphinx_github_changelog",
     "sphinxcontrib.apidoc",
+    "sphinxcontrib.autodoc_pydantic",
     "sphinxcontrib.external_links",
     "sphinxcontrib.jquery",
     "sphinxcontrib.programoutput",
@@ -138,7 +139,6 @@
 autoclass_content = "class"
 autodoc_class_signature = "separated"
 autodoc_default_options = {
-    "inherited-members": "dict",  # show all inherited members
     "member-order": "alphabetical",
     "members": True,
     "show-inheritance": True,
@@ -210,6 +210,21 @@
 apidoc_separate_modules = True
 apidoc_toc_file = "index"
 
+# -- Options for sphinxcontrib.autodoc_pydantic  -----------------------------
+# https://autodoc-pydantic.readthedocs.io/en/stable/users/configuration.html
+autodoc_pydantic_field_doc_policy = "docstring"
+autodoc_pydantic_field_list_validators = False
+autodoc_pydantic_field_show_required = False
+autodoc_pydantic_model_erdantic_figure = False  # cspell:word erdantic
+autodoc_pydantic_model_hide_paramlist = True
+autodoc_pydantic_model_hide_reused_validator = True
+autodoc_pydantic_model_show_config_summary = False
+autodoc_pydantic_model_show_field_summary = False
+autodoc_pydantic_model_show_json = True
+autodoc_pydantic_model_show_json_error_strategy = "coerce"
+autodoc_pydantic_model_show_validator_members = False
+autodoc_pydantic_model_show_validator_summary = False
+autodoc_pydantic_model_undoc_members = True  # cspell:word undoc
 
 # -- Options for sphinxcontrib.external_links   ------------------------------
 # https://sphinxcontribexternal-links.readthedocs.io/latest/configuration.html

pyproject.toml

@@ -62,6 +62,7 @@ yamllint = "*"
 pre-commit = "^3.8.0"
 
 [tool.poetry.group.docs.dependencies]
+autodoc-pydantic = "^2.2.0"
 doc8 = "^1.1.1"
 furo = "^2024.8.6"
 jsx-lexer = "^2.0.1"

runway/cfngin/hooks/ssm/parameter.py

@@ -34,32 +34,7 @@ class _PutParameterResultTypeDef(TypedDict):
 
 
 class ArgsDataModel(BaseModel):
-    """Parameter hook args.
-
-    Attributes:
-        allowed_pattern: A regular expression used to validate the parameter value.
-        data_type: The data type for a String parameter. Supported data types
-            include plain text and Amazon Machine Image IDs.
-        description: Information about the parameter.
-        force: Skip checking the current value of the parameter, just put it.
-            Can be used alongside ``overwrite`` to always update a parameter.
-        key_id: The KMS Key ID that you want to use to encrypt a parameter.
-            Either the default AWS Key Management Service (AWS KMS) key automatically
-            assigned to your AWS account or a custom key.
-            Required for parameters that use the ``SecureString`` data type.
-        name: The fully qualified name of the parameter that you want to add to
-            the system.
-        overwrite: Allow overwriting an existing parameter.
-        policies: One or more policies to apply to a parameter.
-            This field takes a JSON array.
-        tags: Optional metadata that you assign to a resource.
-        tier: The parameter tier to assign to a parameter.
-        type: The type of parameter.
-        value: The parameter value that you want to add to the system.
-            Standard parameters have a value limit of 4 KB.
-            Advanced parameters have a value limit of 8 KB.
-
-    """
+    """Parameter hook args."""
 
     model_config = ConfigDict(extra="ignore", populate_by_name=True)
 

runway/config/models/cfngin/_package_sources.py

@@ -14,14 +14,6 @@ class GitCfnginPackageSourceDefinitionModel(ConfigProperty):
 
     Package source located in a git repository.
 
-    Attributes:
-        branch: Branch name.
-        commit: Commit hash.
-        configs: List of CFNgin config paths to execute.
-        paths: List of paths to append to ``sys.path``.
-        tag: Git tag.
-        uri: Remote git repo URI.
-
     """
 
     model_config = ConfigDict(
@@ -34,27 +26,39 @@ class GitCfnginPackageSourceDefinitionModel(ConfigProperty):
         validate_default=True,
         validate_assignment=True,
     )
+
     branch: Annotated[
         str | None, Field(title="Git Branch", examples=["ENV-dev", "ENV-prod", "master"])
     ] = None
+    """Branch name."""
+
     commit: Annotated[str | None, Field(title="Git Commit Hash")] = None
+    """Commit hash."""
+
     configs: Annotated[
         list[str],
         Field(
             description="Array of paths relative to the root of the package source "
             "for configuration that should be merged into the current configuration file."
         ),
     ] = []
+    """List of CFNgin config paths to execute."""
+
     paths: Annotated[
         list[str],
         Field(
             description="Array of paths relative to the root of the package source to add to $PATH."
         ),
     ] = []
+    """List of paths to append to ``sys.path``."""
+
     tag: Annotated[str | None, Field(title="Git Tag", examples=["1.0.0", "v1.0.0"])] = None
+    """Git tag."""
+
     uri: Annotated[
         str, Field(title="Git Repository URI", examples=["[email protected]:onicagroup/runway.git"])
     ]
+    """Remote git repo URI."""
 
     @model_validator(mode="before")
     @classmethod
@@ -72,11 +76,6 @@ class LocalCfnginPackageSourceDefinitionModel(ConfigProperty):
 
     Package source located on a local disk.
 
-    Attributes:
-        configs: List of CFNgin config paths to execute.
-        paths: List of paths to append to ``sys.path``.
-        source: Source.
-
     """
 
     model_config = ConfigDict(
@@ -97,34 +96,31 @@ class LocalCfnginPackageSourceDefinitionModel(ConfigProperty):
             "for configuration that should be merged into the current configuration file.",
         ),
     ] = []
+    """List of CFNgin config paths to execute."""
+
     paths: Annotated[
         list[str],
         Field(
             description="Array of paths relative to the root of the package source to add to $PATH."
         ),
     ] = []
+    """List of paths to append to ``sys.path``."""
+
     source: Annotated[
         str,
         Field(
             description="Path relative to the current configuration file that is the "
             "root of the local package source."
         ),
     ]
+    """Source."""
 
 
 class S3CfnginPackageSourceDefinitionModel(ConfigProperty):
     """Model for a CFNgin S3 package source definition.
 
     Package source located in AWS S3.
 
-    Attributes:
-        bucket: AWS S3 bucket name.
-        configs: List of CFNgin config paths to execute.
-        key: Object key. The object should be a zip file.
-        paths: List of paths to append to ``sys.path``.
-        requester_pays: AWS S3 requester pays option.
-        use_latest: Use the latest version of the object.
-
     """
 
     model_config = ConfigDict(
@@ -140,41 +136,45 @@ class S3CfnginPackageSourceDefinitionModel(ConfigProperty):
     )
 
     bucket: Annotated[str, Field(title="AWS S3 Bucket Name")]
+    """AWS S3 bucket name."""
+
     configs: Annotated[
         list[str],
         Field(
             description="Array of paths relative to the root of the package source "
             "for configuration that should be merged into the current configuration file.",
         ),
     ] = []
+    """List of CFNgin config paths to execute."""
+
     key: Annotated[str, Field(title="AWS S3 Object Key")]
+    """Object key. The object should be a zip file."""
+
     paths: Annotated[
         list[str],
         Field(
             description="Array of paths relative to the root of the package source to add to $PATH."
         ),
     ] = []
+    """List of paths to append to ``sys.path``."""
+
     requester_pays: Annotated[
         bool,
         Field(
             description="Confirms that the requester knows that they will be charged for the request."
         ),
     ] = False
+    """AWS S3 requester pays option."""
+
     use_latest: Annotated[
         bool,
         Field(description="Update the local copy if the last modified date in AWS S3 changes."),
     ] = True
+    """Use the latest version of the object."""
 
 
 class CfnginPackageSourcesDefinitionModel(ConfigProperty):
-    """Model for a CFNgin package sources definition.
-
-    Attributes:
-        git: Package source located in a git repo.
-        local: Package source located on a local disk.
-        s3: Package source located in AWS S3.
-
-    """
+    """Model for a CFNgin package sources definition."""
 
     model_config = ConfigDict(
         extra="forbid",
@@ -193,15 +193,20 @@ class CfnginPackageSourcesDefinitionModel(ConfigProperty):
         description="Information about git repositories that should be included "
         "in the processing of this configuration file.",
     )
+    """Package source located in a git repo."""
+
     local: list[LocalCfnginPackageSourceDefinitionModel] = Field(
         default=[],
         title="CFNgin Local Package Source Definitions",
         description="Information about local directories that should be included "
         "in the processing of this configuration file.",
     )
+    """Package source located on a local disk."""
+
     s3: list[S3CfnginPackageSourceDefinitionModel] = Field(
         default=[],
         title="CFNgin S3 Package Source Definitions",
         description="Information about a AWS S3 objects that should be "
         "downloaded, unzipped, and included in the processing of this configuration file.",
     )
+    """Package source located in AWS S3."""