feat(Python): Format docstrings (#586)

Format docstrings. See https://aws-cryptographic-material-providers-library.readthedocs.io/en/latest/generated/aws_cryptographic_materialproviders.smithygenerated.aws_cryptography_keystore.models.html for an example. Before, the parameters and function descriptions were not displaying correctly because the docstrings weren't formatted. Now, they are appearing correctly.
smithy-lang · Sep 17, 2024 · dcc45dc · dcc45dc
1 parent 779d38d
commit dcc45dc
Show file tree

Hide file tree

Showing 2 changed files with 12 additions and 14 deletions.
diff --git a/...on-codegen/src/main/java/software/amazon/smithy/python/codegen/DirectedPythonCodegen.java b/...on-codegen/src/main/java/software/amazon/smithy/python/codegen/DirectedPythonCodegen.java
@@ -338,6 +338,7 @@ public void customizeAfterIntegrations(CustomizeDirective<GenerationContext, Pyt
             CodegenUtils.runCommand("python3 " + file, fileManifest.getBaseDir());
         }
         formatCode(fileManifest);
+        formatDocstrings(fileManifest);
         runMypy(fileManifest);
     }
 
@@ -352,6 +353,17 @@ private void formatCode(FileManifest fileManifest) {
         CodegenUtils.runCommand("python3 -m black . --exclude \"\"", fileManifest.getBaseDir());
     }
 
+    private void formatDocstrings(FileManifest fileManifest) {
+        try {
+            CodegenUtils.runCommand("python3 -m docformatter -h", fileManifest.getBaseDir());
+        } catch (CodegenException e) {
+            LOGGER.warning("Unable to find the python package docformatter. Skipping formatting.");
+            return;
+        }
+        LOGGER.info("Running docformatter on generated code");
+        CodegenUtils.runCommand("python3 -m docformatter --recursive .", fileManifest.getBaseDir());
+    }
+
     private void runMypy(FileManifest fileManifest) {
         try {
             CodegenUtils.runCommand("python3 -m mypy -h", fileManifest.getBaseDir());

diff --git a/...morph/smithypython/localservice/extensions/DafnyPythonLocalServiceStructureGenerator.java b/...morph/smithypython/localservice/extensions/DafnyPythonLocalServiceStructureGenerator.java
@@ -374,13 +374,6 @@ protected void writeFromDict(boolean isError) {
       () -> {
         writer.writeDocs(() -> {
           writer.write("Creates a $L from a dictionary.\n", shapeName);
-          writer.write(
-            writer.formatDocs(
-              """
-              The dictionary is expected to use the modeled shape names rather \
-              than the parameter names as keys to be mostly compatible with boto3."""
-            )
-          );
         });
 
         if (shape.members().isEmpty() && !isError) {
@@ -523,13 +516,6 @@ protected void writeAsDict(boolean isError) {
             "Converts the $L to a dictionary.\n",
             symbolProvider.toSymbol(shape).getName()
           );
-          writer.write(
-            writer.formatDocs(
-              """
-              The dictionary uses the modeled shape names rather than the parameter names \
-              as keys to be mostly compatible with boto3."""
-            )
-          );
         });
 
         // If there aren't any optional members, it's best to return immediately.