Skip to content

fix: Strip backslash before # in generated docstrings #677

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Alan4506 merged 2 commits into from
Apr 6, 2026
+1 −2
Merged

fix: Strip backslash before # in generated docstrings #677

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5c0ee7d
fix: Strip backslash before # in generated docstrings
Alan4506 Apr 3, 2026
860716c
Remove unnecessary comments
Alan4506 Apr 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions ...en/core/src/main/java/software/amazon/smithy/python/codegen/writer/MarkdownConverter.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,8 +170,7 @@ private static String postProcessPandocOutput(String output) {

// Remove unnecessary backslash escapes that pandoc adds for markdown
// These characters don't need escaping in Python docstrings
// Handles: [ ] ' { } ( ) < > ` @ _ * | ! ~ $
output = output.replaceAll("\\\\([\\[\\]'{}()<>`@_*|!~$])", "$1");
output = output.replaceAll("\\\\([\\[\\]'{}()<>`@_*|!~$#])", "$1");
Copy link
Copy Markdown
Contributor

@arandito arandito Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: We should be careful with the characters we unescape. Since our docstrings are in markdown, # is a format specifier for headings if it's at the beginning of a line. If we ever have a case where we unescape and it exists at the beginning of a line, it will lead to the entire line being a heading.

It's definitely a small risk but I think we may be able to escape it as \\# to avoid this issue entirely. However, this is also an issue for any Markdown character that can change the line formatting (e.g.> for code blocks). We might consider a double backslash for all the markdown characters but that makes the in-code docstrings more noisy.

This should be fine for now, but we should follow up to update how we escape markdown characters if it becomes a large issue.

Copy link
Copy Markdown
Contributor Author

@Alan4506 Alan4506 Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It makes sense to me. We should look into it more deeply if there is a large issue in the future.


// Replace <note> and <important> tags with admonitions for mkdocstrings
output = replaceAdmonitionTags(output, "note", "Note");
Expand Down
Loading