From 1cf03796d26c8b0e3c0ba146fbf0e9a8482009ef Mon Sep 17 00:00:00 2001
From: SamRemis <sjremis94@gmail.com>
Date: Wed, 26 Mar 2025 13:22:48 -0400
Subject: [PATCH] Add required trait to docs when relevant

---
 .../python/codegen/generators/StructureGenerator.java | 10 +++++++++-
 .../codegen/writer/MarkdownToRstDocConverter.java     | 11 ++++++++---
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/codegen/core/src/main/java/software/amazon/smithy/python/codegen/generators/StructureGenerator.java b/codegen/core/src/main/java/software/amazon/smithy/python/codegen/generators/StructureGenerator.java
index d7cc4dd1b..e0e3d2dcd 100644
--- a/codegen/core/src/main/java/software/amazon/smithy/python/codegen/generators/StructureGenerator.java
+++ b/codegen/core/src/main/java/software/amazon/smithy/python/codegen/generators/StructureGenerator.java
@@ -24,11 +24,13 @@
 import software.amazon.smithy.model.shapes.MemberShape;
 import software.amazon.smithy.model.shapes.Shape;
 import software.amazon.smithy.model.shapes.StructureShape;
+import software.amazon.smithy.model.traits.ClientOptionalTrait;
 import software.amazon.smithy.model.traits.DefaultTrait;
 import software.amazon.smithy.model.traits.DocumentationTrait;
 import software.amazon.smithy.model.traits.ErrorTrait;
 import software.amazon.smithy.model.traits.InputTrait;
 import software.amazon.smithy.model.traits.OutputTrait;
+import software.amazon.smithy.model.traits.RequiredTrait;
 import software.amazon.smithy.model.traits.SensitiveTrait;
 import software.amazon.smithy.model.traits.StreamingTrait;
 import software.amazon.smithy.python.codegen.CodegenUtils;
@@ -316,8 +318,14 @@ private boolean hasDocs() {
 
     private void writeMemberDocs(MemberShape member) {
         member.getMemberTrait(model, DocumentationTrait.class).ifPresent(trait -> {
+            String descriptionPrefix = "";
+            if (member.hasTrait(RequiredTrait.class) && !member.hasTrait(ClientOptionalTrait.class)) {
+                descriptionPrefix = "**[Required]** - ";
+            }
+
             String memberName = symbolProvider.toMemberName(member);
-            String docs = writer.formatDocs(String.format(":param %s: %s", memberName, trait.getValue()));
+            String docs = writer.formatDocs(String.format(":param %s: %s%s",
+                    memberName, descriptionPrefix, trait.getValue()));
             writer.write(docs);
         });
     }
diff --git a/codegen/core/src/main/java/software/amazon/smithy/python/codegen/writer/MarkdownToRstDocConverter.java b/codegen/core/src/main/java/software/amazon/smithy/python/codegen/writer/MarkdownToRstDocConverter.java
index 8e713d0f8..52415c8d8 100644
--- a/codegen/core/src/main/java/software/amazon/smithy/python/codegen/writer/MarkdownToRstDocConverter.java
+++ b/codegen/core/src/main/java/software/amazon/smithy/python/codegen/writer/MarkdownToRstDocConverter.java
@@ -6,6 +6,8 @@
 
 import static org.jsoup.nodes.Document.OutputSettings.Syntax.html;
 
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 import org.commonmark.node.BlockQuote;
 import org.commonmark.node.FencedCodeBlock;
 import org.commonmark.node.Heading;
@@ -52,8 +54,11 @@ public static MarkdownToRstDocConverter getInstance() {
     }
 
     public String convertCommonmarkToRst(String commonmark) {
-        String html =
-                HtmlRenderer.builder().escapeHtml(false).build().render(MARKDOWN_PARSER.parse(commonmark));
+        String html = HtmlRenderer.builder().escapeHtml(false).build().render(MARKDOWN_PARSER.parse(commonmark));
+        //Replace the outer HTML paragraph tag with a div tag
+        Pattern pattern = Pattern.compile("^<p>(.*)</p>$", Pattern.DOTALL);
+        Matcher matcher = pattern.matcher(html);
+        html = matcher.replaceAll("<div>$1</div>");
         Document document = Jsoup.parse(html);
         RstNodeVisitor visitor = new RstNodeVisitor();
         document.body().traverse(visitor);
@@ -75,7 +80,7 @@ public void head(Node node, int depth) {
                         int secondColonIndex = text.indexOf(':',  1);
                         writer.write(text.substring(0, secondColonIndex + 1));
                         //TODO right now the code generator gives us a mixture of
-                        // commonmark and HTML (for instance :param xyz: <p> docs
+                        // RST and HTML (for instance :param xyz: <p> docs
                         // </p>).  Since we standardize to html above, that <p> tag
                         // starts a newline.  We account for that with this if/else
                         // statement, but we should refactor this in the future to