Skip to content

Commit 93d5abc

Browse files
SamRemisSamRemis
committed
Docs generation updates
Migrate to using SimpleCodeWriter for writing rst strings
1 parent ff78144 commit 93d5abc

File tree

5 files changed

+99
-58
lines changed

5 files changed

+99
-58
lines changed

‎codegen/aws/core/src/test/java/software/amazon/smithy/python/aws/codegen/MarkdownToRstDocConverterTest.java‎

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -22,88 +22,88 @@ public void setUp() {
2222
@Test
2323
public void testConvertCommonmarkToRstWithTitleAndParagraph() {
2424
String html = "<html><body><h1>Title</h1><p>Paragraph</p></body></html>";
25-
String expected = "\n\nTitle\n=====\nParagraph\n";
25+
String expected = "Title\n=====\nParagraph";
2626
String result = markdownToRstDocConverter.convertCommonmarkToRst(html);
27-
assertEquals(expected, result);
27+
assertEquals(expected, result.trim());
2828
}
2929

3030
@Test
3131
public void testConvertCommonmarkToRstWithImportantNote() {
3232
String html = "<html><body><important>Important note</important></body></html>";
33-
String expected = "\n\n.. important::\n Important note\n";
33+
String expected = ".. important::\n Important note";
3434
String result = markdownToRstDocConverter.convertCommonmarkToRst(html);
35-
assertEquals(expected, result);
35+
assertEquals(expected, result.trim());
3636
}
3737

3838
@Test
3939
public void testConvertCommonmarkToRstWithList() {
4040
String html = "<html><body><ul><li>Item 1</li><li>Item 2</li></ul></body></html>";
41-
String expected = "\n\n* Item 1\n\n* Item 2\n\n";
41+
String expected = "* Item 1\n* Item 2";
4242
String result = markdownToRstDocConverter.convertCommonmarkToRst(html);
43-
assertEquals(expected, result);
43+
assertEquals(expected, result.trim());
4444
}
4545

4646
@Test
4747
public void testConvertCommonmarkToRstWithMixedElements() {
4848
String html = "<html><body><h1>Title</h1><p>Paragraph</p><ul><li>Item 1</li><li>Item 2</li></ul></body></html>";
49-
String expected = "\n\nTitle\n=====\nParagraph\n\n* Item 1\n\n* Item 2\n\n";
49+
String expected = "Title\n=====\nParagraph\n\n\n* Item 1\n* Item 2";
5050
String result = markdownToRstDocConverter.convertCommonmarkToRst(html);
51-
assertEquals(expected, result);
51+
assertEquals(expected, result.trim());
5252
}
5353

5454
@Test
5555
public void testConvertCommonmarkToRstWithNestedElements() {
5656
String html = "<html><body><h1>Title</h1><p>Paragraph with <strong>bold</strong> text</p></body></html>";
57-
String expected = "\n\nTitle\n=====\nParagraph with **bold** text\n";
57+
String expected = "Title\n=====\nParagraph with **bold** text";
5858
String result = markdownToRstDocConverter.convertCommonmarkToRst(html);
59-
assertEquals(expected, result);
59+
assertEquals(expected, result.trim());
6060
}
6161

6262
@Test
6363
public void testConvertCommonmarkToRstWithAnchorTag() {
6464
String html = "<html><body><a href='https://example.com'>Link</a></body></html>";
65-
String expected = "\n`Link <https://example.com>`_";
65+
String expected = "`Link <https://example.com>`_";
6666
String result = markdownToRstDocConverter.convertCommonmarkToRst(html);
67-
assertEquals(expected, result);
67+
assertEquals(expected, result.trim());
6868
}
6969

7070
@Test
7171
public void testConvertCommonmarkToRstWithBoldTag() {
7272
String html = "<html><body><b>Bold text</b></body></html>";
73-
String expected = "\n**Bold text**";
73+
String expected = "**Bold text**";
7474
String result = markdownToRstDocConverter.convertCommonmarkToRst(html);
75-
assertEquals(expected, result);
75+
assertEquals(expected, result.trim());
7676
}
7777

7878
@Test
7979
public void testConvertCommonmarkToRstWithItalicTag() {
8080
String html = "<html><body><i>Italic text</i></body></html>";
81-
String expected = "\n*Italic text*";
81+
String expected = "*Italic text*";
8282
String result = markdownToRstDocConverter.convertCommonmarkToRst(html);
83-
assertEquals(expected, result);
83+
assertEquals(expected, result.trim());
8484
}
8585

8686
@Test
8787
public void testConvertCommonmarkToRstWithCodeTag() {
8888
String html = "<html><body><code>code snippet</code></body></html>";
89-
String expected = "\n``code snippet``";
89+
String expected = "``code snippet``";
9090
String result = markdownToRstDocConverter.convertCommonmarkToRst(html);
91-
assertEquals(expected, result);
91+
assertEquals(expected, result.trim());
9292
}
9393

9494
@Test
9595
public void testConvertCommonmarkToRstWithNoteTag() {
9696
String html = "<html><body><note>Note text</note></body></html>";
97-
String expected = "\n\n.. note::\n Note text\n";
97+
String expected = ".. note::\n Note text";
9898
String result = markdownToRstDocConverter.convertCommonmarkToRst(html);
99-
assertEquals(expected, result);
99+
assertEquals(expected, result.trim());
100100
}
101101

102102
@Test
103103
public void testConvertCommonmarkToRstWithNestedList() {
104104
String html = "<html><body><ul><li>Item 1<ul><li>Subitem 1</li></ul></li><li>Item 2</li></ul></body></html>";
105-
String expected = "\n\n* Item 1\n * Subitem 1\n\n* Item 2\n\n";
105+
String expected = "* Item 1\n\n * Subitem 1\n* Item 2";
106106
String result = markdownToRstDocConverter.convertCommonmarkToRst(html);
107-
assertEquals(expected, result);
107+
assertEquals(expected, result.trim());
108108
}
109109
}

‎codegen/core/src/main/java/software/amazon/smithy/python/codegen/ClientGenerator.java‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
import software.amazon.smithy.python.codegen.integrations.PythonIntegration;
2525
import software.amazon.smithy.python.codegen.integrations.RuntimeClientPlugin;
2626
import software.amazon.smithy.python.codegen.sections.*;
27+
import software.amazon.smithy.python.codegen.writer.MarkdownToRstDocConverter;
2728
import software.amazon.smithy.python.codegen.writer.PythonWriter;
2829
import software.amazon.smithy.utils.SmithyInternalApi;
2930

@@ -60,6 +61,8 @@ private void generateService(PythonWriter writer) {
6061
var docs = service.getTrait(DocumentationTrait.class)
6162
.map(StringTrait::getValue)
6263
.orElse("Client for " + serviceSymbol.getName());
64+
String rstDocs =
65+
MarkdownToRstDocConverter.getInstance().convertCommonmarkToRst(docs);
6366
writer.writeDocs(() -> {
6467
writer.write("""
6568
$L
@@ -68,7 +71,7 @@ private void generateService(PythonWriter writer) {
6871
endpoint for HTTP services or auth credentials.
6972
7073
:param plugins: A list of callables that modify the configuration dynamically. These
71-
can be used to set defaults, for example.""", docs);
74+
can be used to set defaults, for example.""", rstDocs);
7275
});
7376

7477
var defaultPlugins = new LinkedHashSet<SymbolReference>();
@@ -866,14 +869,17 @@ private void writeSharedOperationInit(PythonWriter writer, OperationShape operat
866869
.orElse("The operation's input.");
867870

868871
writer.write("""
869-
:param input: $L
870-
872+
$L
873+
""",docs);
874+
writer.write("");
875+
writer.write(":param input: $L", inputDocs);
876+
writer.write("");
877+
writer.write("""
871878
:param plugins: A list of callables that modify the configuration dynamically.
872879
Changes made by these plugins only apply for the duration of the operation
873880
execution and will not affect any other operation invocations.
881+
""");
874882

875-
$L
876-
""", inputDocs, docs);
877883
});
878884

879885
var defaultPlugins = new LinkedHashSet<SymbolReference>();

‎codegen/core/src/main/java/software/amazon/smithy/python/codegen/generators/SetupGenerator.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -334,7 +334,7 @@ private static void writeConf(
334334
}
335335
}
336336
337-
autodoc_typehints = 'both'
337+
autodoc_typehints = 'description'
338338
""", projectName, version, projectName);
339339
});
340340
}

‎codegen/core/src/main/java/software/amazon/smithy/python/codegen/writer/MarkdownToRstDocConverter.java‎

Lines changed: 62 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
import org.jsoup.nodes.TextNode;
2222
import org.jsoup.select.NodeVisitor;
2323
import software.amazon.smithy.utils.SetUtils;
24+
import software.amazon.smithy.utils.SimpleCodeWriter;
2425
import software.amazon.smithy.utils.SmithyInternalApi;
2526

2627
/**
@@ -60,9 +61,9 @@ public String convertCommonmarkToRst(String commonmark) {
6061
}
6162

6263
private static class RstNodeVisitor implements NodeVisitor {
63-
//TODO migrate away from StringBuilder to use a SimpleCodeWriter
64-
private final StringBuilder sb = new StringBuilder();
64+
SimpleCodeWriter writer = new SimpleCodeWriter();
6565
private boolean inList = false;
66+
private boolean inParam = false;
6667
private int listDepth = 0;
6768

6869
@Override
@@ -71,47 +72,72 @@ public void head(Node node, int depth) {
7172
TextNode textNode = (TextNode) node;
7273
String text = textNode.text();
7374
if (!text.trim().isEmpty()) {
74-
sb.append(text);
75-
// Account for services making a paragraph tag that's empty except
76-
// for a newline
75+
if (text.startsWith(":param ")) {
76+
//TODO streamline this code by calling writer.writedocs on
77+
// param and the parameters separately. It should probably
78+
// be this way instead of the other way around; we want to be
79+
// able to perma-indent
80+
int secondColonIndex = text.indexOf(':', 1);
81+
writer.write(text.substring(0, secondColonIndex + 1));
82+
if (secondColonIndex +1 == text.strip().length()) {
83+
writer.indent();
84+
writer.ensureNewline();
85+
inParam = true;
86+
} else {
87+
writer.ensureNewline();
88+
writer.indent();
89+
writer.write(text.substring(secondColonIndex + 1));
90+
writer.dedent();
91+
}
92+
} else {
93+
writer.writeInline(text);
94+
}
95+
// Account for services making a paragraph tag that's empty except
96+
// for a newline
7797
} else if (node.parent() instanceof Element && ((Element) node.parent()).tagName().equals("p")) {
78-
sb.append(text.replaceAll("[ \\t]+", ""));
98+
writer.writeInline(text.replaceAll("[ \\t]+", ""));
7999
}
80100
} else if (node instanceof Element) {
81101
Element element = (Element) node;
82102
switch (element.tagName()) {
83103
case "a":
84-
sb.append("`");
104+
writer.writeInline("`");
85105
break;
86106
case "b":
87107
case "strong":
88-
sb.append("**");
108+
writer.writeInline("**");
89109
break;
90110
case "i":
91111
case "em":
92-
sb.append("*");
112+
writer.writeInline("*");
93113
break;
94114
case "code":
95-
sb.append("``");
115+
writer.writeInline("``");
96116
break;
97117
case "important":
98-
sb.append("\n.. important::\n ");
118+
writer.ensureNewline();
119+
writer.write("");
120+
writer.openBlock(".. important::");
99121
break;
100122
case "note":
101-
sb.append("\n.. note::\n ");
123+
writer.ensureNewline();
124+
writer.write("");
125+
writer.openBlock(".. note::");
102126
break;
103127
case "ul":
128+
if (inList) {
129+
writer.indent();
130+
}
104131
inList = true;
105132
listDepth++;
106-
sb.append("\n");
133+
writer.ensureNewline();
134+
writer.write("");
107135
break;
108136
case "li":
109-
if (inList) {
110-
sb.append(" ".repeat(listDepth - 1)).append("* ");
111-
}
137+
writer.writeInline("* ");
112138
break;
113139
case "h1":
114-
sb.append("\n");
140+
writer.ensureNewline();
115141
break;
116142
default:
117143
break;
@@ -125,41 +151,47 @@ public void tail(Node node, int depth) {
125151
Element element = (Element) node;
126152
switch (element.tagName()) {
127153
case "a":
128-
sb.append(" <").append(element.attr("href")).append(">`_");
154+
String href = element.attr("href");
155+
if (!href.isEmpty()) {
156+
writer.writeInline(" <").writeInline(href).writeInline(">`_");
157+
} else {
158+
writer.writeInline("`");
159+
}
129160
break;
130161
case "b":
131162
case "strong":
132-
sb.append("**");
163+
writer.writeInline("**");
133164
break;
134165
case "i":
135166
case "em":
136-
sb.append("*");
167+
writer.writeInline("*");
137168
break;
138169
case "code":
139-
sb.append("``");
170+
writer.writeInline("``");
140171
break;
141172
case "important":
142173
case "note":
174+
writer.closeBlock("");
175+
break;
143176
case "p":
144-
sb.append("\n");
177+
writer.ensureNewline();
178+
writer.write("");
145179
break;
146180
case "ul":
147181
listDepth--;
148182
if (listDepth == 0) {
149183
inList = false;
184+
} else {
185+
writer.dedent();
150186
}
151-
if (sb.charAt(sb.length() - 1) != '\n') {
152-
sb.append("\n\n");
153-
}
187+
writer.ensureNewline();
154188
break;
155189
case "li":
156-
if (sb.charAt(sb.length() - 1) != '\n') {
157-
sb.append("\n\n");
158-
}
190+
writer.ensureNewline();
159191
break;
160192
case "h1":
161193
String title = element.text();
162-
sb.append("\n").append("=".repeat(title.length())).append("\n");
194+
writer.ensureNewline().writeInline("=".repeat(title.length())).ensureNewline();
163195
break;
164196
default:
165197
break;
@@ -169,7 +201,7 @@ public void tail(Node node, int depth) {
169201

170202
@Override
171203
public String toString() {
172-
return sb.toString();
204+
return writer.toString();
173205
}
174206
}
175207
}

‎codegen/core/src/main/java/software/amazon/smithy/python/codegen/writer/PythonWriter.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,9 @@ private static void wrapLine(String line, StringBuilder wrappedText) {
174174
while (line.length() > MAX_LINE_LENGTH) {
175175
int wrapAt = findWrapPosition(line, MAX_LINE_LENGTH);
176176
wrappedText.append(indentStr).append(line, 0, wrapAt).append("\n");
177+
if (line.startsWith("* ")) {
178+
indentStr += " ";
179+
}
177180
line = line.substring(wrapAt).trim();
178181
if (line.isEmpty()) {
179182
return;

0 commit comments

Comments
 (0)